建置及部署 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 專案：

  1. 預編譯 TypeScript：部署前先在本地編譯 TypeScript 程式碼。
  2. 安裝相依套件：在本機執行 npm install 或 yarn install，以安裝相依套件。
  3. 建置驗證：確保您的建置輸出在本地環境中正常運作。
  4. 部署編譯輸出：部署已編譯的 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

你可以設定以下工具來使用本地建置：

遠端組建

使用 遠端建置時，Functions 平台負責套件安裝、TypeScript 編譯，並確保與遠端執行環境相容。

使用遠端編譯後，部署套件較小，因為不需要包含 node_modules 或編譯的 JavaScript 檔案。

當你使用遠端建置部署 TypeScript 專案時：

  1. 自動偵測：平台會依據是否存在 tsconfig.json 來偵測 TypeScript 專案。
  2. 編譯：平台會根據你專案的 TypeScript 設定來編譯 TypeScript 檔案。
  3. 相依性安裝：平台會從 dependencies 同時安裝 devDependencies 和 package.json，因為編譯需要使用建置時套件，例如 typescript。
  4. 優化：平台僅在最終部署套件中包含必要的檔案。

你可以在使用下列工具發佈 TypeScript 應用程式時，使用遠端建置：

若要啟用其他情境的遠端建置，例如 使用 Azure Pipelines 的持續交付，請參見 啟用遠端建置。

自訂相依性

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
  • 上次更新時間：