建構 Node.js 應用程式

指定 Node.js 版本

建構套件專案支援 Node.js 的「目前」和「有效 LTS」版本。您可以使用舊版 Node.js，但專案可能不會主動維護這些版本。

使用package.json

您可以在部署期間，透過設定 package.json 檔案中的 engines.node 欄位，指定應用程式的 Node.js 版本。如要設定建構套件，在部署應用程式時使用最新版 Node.js，請在 package.json 中新增下列值：

"engines": {
  "node": "24.x.x"
}

使用GOOGLE_NODEJS_VERSION

您也可以使用 GOOGLE_NODEJS_VERSION 環境變數指定 Node.js 版本。如果同時設定這兩項，系統會優先採用 GOOGLE_NODEJS_VERSION 值，而非 engines.node 屬性。如果您未提供版本，建構包會使用最新 LTS 版的 Node.js。

如要設定建構套件，在部署應用程式時使用 Node.js 24，請執行下列指令：

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=24.x.x

您也可以使用 project.toml 專案描述元，在專案檔案旁編碼環境變數。請參閱使用環境變數建構應用程式的說明。

提示

  • engines.node 欄位可以採用 semver 限制。我們用於 Node.js 建構套件的特定程式庫是 Masterminds/semver
  • 請勿在 engines.node 欄位中使用大於 (>) 規範。
  • 將應用程式部署至 App Engine 標準環境時，engines.node 屬性應與 app.yaml 中指定的執行階段相容。如要進一步瞭解 package.json 檔案中的 engines.node 設定選項，請參閱 NPM 官方說明文件中的引擎主題。
  • 將函式部署到 Cloud Run functions 時，engines.node 屬性應與用於部署函式的執行階段相容

安裝依附元件

NPM 是所有 Node.js 版本的預設套件管理工具。下列章節列出 Node.js 應用程式的相容依附元件。

NPM 套件管理工具

  • NPM 是預設的套件管理工具。
  • 請盡可能使用 package-lock.json，以提升快取效能。
  • 根據預設，系統只會安裝正式版依附元件。
  • 使用 package.json 檔案中的 engines.npm 欄位指定 npm 版本。詳情請參閱 NPM 說明文件。

Yarn 套件管理工具

  • 在專案中加入 yarn.lock 檔案時，建構套件會使用 Yarn。
  • 在 package.json 檔案的 engines.yarn 欄位中指定 yarn 版本。
  • 如果專案包含 .yarn/cache 資料夾，建構包就會支援 Yarn2 PnP 模式。

Pnpm 套件管理工具

  • 在專案中加入 pnpm-lock.yaml 檔案時，buildpack 會使用 Pnpm。
  • 在 package.json 檔案的 engines.pnpm 欄位中指定 pnpm 版本。
  • 如需實際運作的範例，請參閱 sample-node-pnpm。

Bun 套件管理工具

Node.js 建構套件支援 Bun 套件管理工具 google.nodejs.bun buildpack，可安裝依附元件。如要使用 Bun 套件管理工具，請按照下列步驟操作：

  • 在根目錄中建立 bun.lock 或 bun.lockb 檔案，以供自動偵測。
  • 或者，您也可以將 GOOGLE_PACKAGE_MANAGER 環境變數明確設為 bun。使用這個方法時，您不需要建立及維護鎖定檔。
  • 專案必須包含 package.json 檔案。您可以在 package.json 檔案的 engines.bun 或 packageManager 欄位中指定 Bun 版本。如果未指定版本，建構套件預設會使用最新的穩定版。

如要進一步瞭解如何部署至 Cloud Run，請參閱「在 Node.js 中指定依附元件」。

如要進一步瞭解 Bun 套件管理工具，請參閱 Bun 說明文件。

套件管理工具優先順序

Node.js 建構包會根據設定，按照下列優先順序決定套件管理員：

  1. GOOGLE_PACKAGE_MANAGER 的優先順序一律最高。這個環境變數僅支援 bun (預先發布版)。

  2. 建構包會依下列順序檢查鎖定檔：

    • Yarn - yarn.lock
    • pnpm - pnpm-lock.yaml
    • 麵包 - bun.lock 或 bun.lockb
    • NPM - package-lock.json

  3. 如果未設定環境變數或使用鎖定檔，建構套件預設會使用 NPM。

私人模組

如要使用私人 npm 模組，請在函式目錄的 .npmrc 檔案中提供驗證登錄檔的設定。如果您使用 Yarn 2 以上版本做為套件管理工具，這個檔案會命名為 .yarnrc.yml。

Artifact Registry 的私人模組

Artifact Registry Node.js 套件存放區可託管函式的私人模組。部署 Buildpacks 函式時，建構程序會自動為 Cloud Build 服務帳戶產生 Artifact Registry 憑證。使用 NPM 或 Yarn 第 1 版時，只需在 .npmrc 檔案中列出 Artifact Registry 存放區。舉例來說，使用 NPM 或 Yarn 第 1 版時：

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

如果您使用 Yarn 第 2 版以上，只需在 .yarnrc.yml 檔案中列出 Artifact Registry 存放區，無須提供額外憑證。例如：

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

其他存放區的私人模組

npm 文件說明如何建立自訂唯讀存取權杖。在主目錄中建立的 .npmrc 檔案包含讀取/寫入憑證，因此我們不建議使用。部署期間不需要寫入權限，且這項權限可能會帶來安全風險。

.npmrc 檔案可能會增加函式的部署時間，因此如果您未使用私人存放區，請不要加入這個檔案。

檔案格式

如果您使用 .npmrc 檔案設定自訂驗證權杖，請加入下列內容：

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

取代：

  • REGISTRY_DOMAIN：私人 npm 登錄檔的網域名稱。舉例來說，如果存放區主機是 npmjs.org，請將這個欄位設為 registry.npmjs.org。

  • AUTH_TOKEN：npm 登錄檔的授權權杖。 這可以是權杖的文字值，也可以是文字字串 ${NPM_TOKEN}，npm 指令會將其替換為環境中的實際權杖值。

    您可以使用 gcloud functions deploy 指令的 --set-build-env-vars 引數，設定 $NPM_TOKEN 環境變數。如要進一步瞭解 NPM 驗證權杖，請參閱 NPM 私人模組教學課程。

在部署期間執行自訂建構步驟

根據預設，如果 package.json 檔案中指定了指令碼，系統就會執行 npm run build。不過，您可以指定自訂建構步驟，覆寫預設行為，並在建構期間只執行所需的指令碼。您可以使用 GOOGLE_NODE_RUN_SCRIPTS 環境變數或 gcp-build，控管 package.json 檔案中的建構步驟。

你只能使用一種方法。請注意，GOOGLE_NODE_RUN_SCRIPTS 環境變數的優先順序較高，會覆寫 package.json 中為 gcp-build 指定的任何項目。

根據預設，設定自訂建構步驟時，系統會先安裝 package.json 檔案中的 dependencies 和 devDependencies，再執行任何指令碼或指令。如要覆寫預設行為，可以使用 NODE_ENV 環境變數。

使用GOOGLE_NODE_RUN_SCRIPTS

您可以將 GOOGLE_NODE_RUN_SCRIPTS 環境變數傳遞至建構作業，藉此控管要執行的指令碼。您可以指定一或多個指令碼，或傳遞空白環境變數 (例如 GOOGLE_NODE_RUN_SCRIPTS=)，防止執行預設行為。如需完整詳細資料，請參閱「環境變數」。

使用package.json

在 package.json 檔案中新增 gcp-build 只會執行 npm run gcp-build，也就是說，這會覆寫預設行為。您可以指定一或多個指令，也可以指定空字串來防止執行任何指令，例如 "gcp-build":""。

"scripts": {
  ...
  "gcp-build": "npm run lint && npm run build"
  ...
}

應用程式進入點

Node.js 建構套件會執行您在 package.json 檔案的 scripts.start 欄位中指定的指令。如未設定 scripts.start 欄位，建構包會執行 npm start 指令。

建議使用 Procfile，因為這樣可以將套件管理工具從路徑中移除，並直接執行。

環境變數

您可以設定環境變數來設定容器映像檔的建構作業。

Node.js 建構套件支援下列環境變數，可自訂容器。

NODE_ENV

在建構期間指定開發環境；為 npm install 設定。

範例： NODE_ENV=development 會安裝 package.json 中指定的 dependencies 和 devDependencies。

NPM_CONFIG_<key>

指定設定參數，例如 NPM_CONFIG_FLAG=value 會將 -flag=value 傳遞至 npm 指令。

如要瞭解這個環境變數，請參閱 NPM 說明文件中的「Config」。

GOOGLE_PACKAGE_MANAGER (預先發布版)

僅支援 Bun 套件管理工具。這個環境變數會覆寫自動偵測程序。舉例來說，即使您未建立鎖定檔，GOOGLE_PACKAGE_MANAGER=bun 也會強制使用 Bun。

GOOGLE_NODE_RUN_SCRIPTS

指定要在安裝依附元件後執行的 package.json npm 指令碼排序清單。清單必須以半形逗號分隔，並按照您列出各個指令碼的順序執行。

指定 GOOGLE_NODE_RUN_SCRIPTS 時，系統只會執行您列出的指令碼。舉例來說，如要防止預設的 npm run build 執行，請指定不含值的環境變數。

範例：

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build 會執行 npm run lint，然後執行 npm run build。
  • GOOGLE_NODE_RUN_SCRIPTS= 不會執行任何指令碼。