构建和部署 TypeScript Azure Functions 应用

Azure Functions 支持多种构建选项，用于将你的 TypeScript 应用发布到 Azure。根据本地环境、应用依赖、TypeScript编译需求和运行时需求选择构建方法。

选择构建方法

因子	本地组装（推荐）	远程构建
最适用于	复杂的构建、Monorepo、自定义工具	简单项目，快速部署
软件包大小	更大（包括 `node_modules`）	较小（依赖项已安装在 Azure 中）
TypeScript 编译	你在本地编译	Azure 会自动编译
原生二进制兼容性	你必须匹配目标架构	自动处理（Linux x64）
构建超时风险	无（在你的计算机上运行）	对于大型依赖集，这是可能的
控制	全套（任何构建工具、捆绑器、优化器）	仅限于平台默认设置

关于私有 npm 包或自定义注册表，请参见自定义依赖。

打包你的应用进行部署

在将 TypeScript 函数应用部署到 Azure 时，你的部署包必须满足以下要求：

需要 JavaScript 输出：Azure Functions 运行 JavaScript，因此 TypeScript 必须在部署前或部署期间编译。
根级别 host.json：确保单个 host.json 文件位于部署包的根目录中，而不是嵌套在子文件夹中。
package.json main 字段：函数运行时在启动时读取该字段以定位和索引你的函数。它必须指向你编译后的JavaScript入口点（例如， dist/src/index.js）。
排除开发文件：使用文件 .funcignore 排除不必要的文件，如本例所示：
```
.git/
.vscode/
local.settings.json
test/
.env
tsconfig.json
src/
node_modules/
```

在规划部署时，也请牢记以下权衡：

构建环境必须与生产环境匹配：带有原生二进制的依赖必须为 Linux x64 架构构建。远程构建会自动处理;本地构建时，可以考虑使用 Docker 或容器化构建环境。
部署包大小影响冷启动：依赖集大会增加冷启动延迟，因为运行时必须单独加载每个文件。用esbuild或webpack等工具将应用打包到更少的文件中，可以显著减少启动时间。
远程构建有超时限制：如果依赖安装或 TypeScript 编译超过平台限制，构建将失败。对于大型项目，使用带有预建依赖的本地构建。
模块初始化有时间限制：Node.js 模块加载和启动时的功能索引是时间限制的。尽量减少顶层导入，或者尽可能使用动态导入。

本地生成

如果你没有明确请求远程构建，你的机器会安装依赖并编译TypeScript。然后你将整个编译好的项目和依赖打包并部署到函数应用中。

本地构建会上传更大的包，但你可以完全控制构建过程，并确保与开发环境的兼容性。

对于使用本地构建的TypeScript项目：

预编译TypeScript：部署前先在本地编译你的TypeScript代码。
安装依赖：运行 npm install 或 yarn install 本地安装依赖。
构建验证：确保你的构建输出在本地环境中正常工作。
部署编译输出：部署已编译的JavaScript及其依赖。

本地构建示例构建命令：

# Install dependencies
npm install

# Compile TypeScript
npm run build
# or
tsc

# Deploy with local build (no remote compilation)
func azure functionapp publish <APP_NAME> --no-build

你可以配置以下工具来使用本地构建：

Azure Functions Core Tools：使用func azure functionapp publish带有--no-build标志。
AZ CLI： az functionapp deployment source config-zip
使用 GitHub Actions 持续交付：将remote-build参数设置为false以应用于弹性消耗计划，或将scm-do-build-during-deployment和enable-oryx-build设置为false以适用于专用计划。

远程生成

使用远程构建时，Functions平台负责包的安装、TypeScript编译，并确保与远程运行环境的兼容性。

使用远程构建，部署包更小，因为不需要包含 node_modules 或编译的JavaScript文件。

当你通过远程构建部署 TypeScript 项目时：

自动检测：平台通过是否存在 tsconfig.json 来识别 TypeScript 项目。
编译：平台通过使用你项目的 TypeScript 配置编译 TypeScript 文件。
依赖安装：平台会从 dependencies 同时安装 devDependencies 和 package.json，因为编译时需要像 typescript 这样的构建时软件包。
优化：平台仅在最终部署包中包含必要的文件。

你可以在发布TypeScript应用时使用远程构建，使用以下工具：

Azure Functions 核心工具：func azure functionapp publish 命令需要使用 --build-remote=true 标志，以启用 Node.js 应用的远程生成。
AZ CLI： az functionapp deployment source config-zip 需要该 --build-remote=true 标志来启用 Node.js 应用的远程构建。
Visual Studio Code： Azure Functions：部署到 Azure... 命令始终使用远程生成。
使用 GitHub Actions 实现持续交付：当参数为 Flex Consumption 计划时，或当参数remote-buildtrue和scm-do-build-during-deployment为专用计划时，enable-oryx-build 操作使用远程构建。

自定义依赖项

Azure Functions 通过使用自定义 npm 注册表、私有包或本地包，支持自定义和私有 npm 依赖。

带自定义 npm 注册表的远程构建

当你的私有包在自定义的 npm 注册表中可用时，你可以在配置注册表位置后请求远程构建。

要使用自定义注册表，请在项目根创建 .npmrc 一个文件：

registry=https://your-private-registry.com/
//your-private-registry.com/:_authToken=${NPM_TOKEN}

本地包和私有模块

构建 TypeScript Azure 函数应用时支持本地包和私有模块。

若要通过远程构建包含本地包，请在 package.json 文件中引用它们：

{
  "dependencies": {
    "@azure/functions": "^4.0.0",
    "my-private-package": "file:../my-private-package",
    "another-local-package": "file:./packages/local-lib"
  }
}

如需通过本地构建包含本地依赖项，请先在本地安装这些依赖项，并在禁用远程构建的情况下进行部署：

# Install all dependencies including local ones
npm install

# Build your TypeScript project
npm run build

# Publish with local build
func azure functionapp publish <APP_NAME> --no-build

使用工作区包

对于 monorepo 或 npm 工作区设置，请在文件 package.json 中使用 npm workspaces 来参考共享包：

{
  "name": "functions-app",
  "dependencies": {
    "@azure/functions": "^4.0.0",
    "@mycompany/shared-lib": "workspace:*"
  },
  "workspaces": [
    "packages/*"
  ]
}

部署前捆绑

使用webpack、esbuild或rollup等捆绑工具，在部署前创建一个单一捆绑包：

# Bundle your application
npm run bundle

# Deploy the bundled output
func azure functionapp publish <APP_NAME> --no-build

Last updated on 2026-08-14