在 Node.js 中指定依附元件

函式可使用外部 Node.js 模組以及本機資料。Node.js 中的依附元件是透過 npm 管理，並以稱為 package.json 的中繼資料檔案表示。您可以使用 npm、yarn、pnpm 或 Bun 安裝 Node.js 依附元件。

Node.js Functions Framework 是所有函式的必要依附元件。雖然系統會在建立函式時為您安裝 Cloud Run functions，但我們建議您將其新增為依附元件，以求明確。

如果函式依附於私人依附元件，建議您將 functions-framework 鏡像到私人註冊資料庫。將鏡像的 functions-framework 新增為函式的依附元件，避免從公開網際網路安裝套件。

如要為函式指定依附元件，請將其新增到 package.json 檔案中。

如果 Node.js 建構包在專案中偵測到鎖定檔案 (例如 package-lock.json、yarn.lock、pnpm-lock.yaml、bun.lock 或 bun.lockb)，使用 npm ci、yarn install、pnpm install 或 bun install 安裝依附元件時，系統會優先採用該鎖定檔案。

以下範例列出 package.json 檔案中的依附元件：

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

Cloud Run 會在函式中匯入依附元件：

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

在本機使用 npm 安裝 Node.js 模組

如要在本機安裝 Node.js 模組，最簡單的方法是在包含 Cloud Run 函式的資料夾中使用 npm install 指令。舉例來說，下列指令會新增 uuid 模組：

npm install uuid

這項操作結合了兩個步驟：

1. 此指令會在 package.json 檔案中，將最新版本的模組標示為依附元件。這非常重要：Cloud Run functions 只會安裝 package.json 檔案中宣告的模組。
2. 此指令會將模組下載到 node_modules 目錄，讓您在本機開發時使用。

如果您的電腦未安裝 npm，請取得 npm。

注意：npm 套件適用於各種 Google Cloud 產品，請參閱 Node.js 用戶端程式庫。

設定部署作業依附元件

您可以安裝 NPM、Yarn 或 Pnpm 的實際依附元件：

NPM 套件管理工具

部署函式時，Cloud Run functions 會使用 npm install 指令安裝 package.json 檔案中宣告的依附元件：

npm install --production

Yarn 套件管理工具

在 Node.js 8 以上版本的執行階段中，如果存在 yarn.lock 檔案，Cloud Run functions 會改用 yarn install 指令：

yarn install --production

Pnpm 套件管理工具

在 Node.js 8 以上版本的執行階段中，如果存在 pnpm-lock.yaml 檔案，Cloud Run functions 會改用 pnpm install 指令：

pnpm install

Bun 套件管理工具

預先發布版 — Support for the Bun package manager

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

Node.js 建構套件支援 Bun 套件管理工具。使用 Bun 套件管理工具時，您可以安裝依附元件，同時維持現有的 Node.js 專案結構和執行階段版本。你可以選擇下列任一機制，使用 Bun 安裝依附元件：

• 自動偵測：在專案中加入 bun.lock 或 bun.lockb 檔案時，Node.js 建構包會偵測 Bun 套件管理工具。如要使用 Bun 設定自動偵測功能，請按照下列步驟操作：

  1. 建立鎖定檔：

     bun install --lockfile-only
     

  2. 執行下列指令，部署至 Cloud Run：

      gcloud run deploy --source . --base-image=nodejs24
     

• 明確選擇加入：將 GOOGLE_PACKAGE_MANAGER 環境變數設為 bun。使用這個方法時，您不需要建立及維護鎖定檔。執行下列指令，部署至 Cloud Run：

  gcloud run deploy --source . --base-image=nodejs24 --set-build-env-vars GOOGLE_PACKAGE_MANAGER=bun
  

雖然建構套件會使用 Bun 安裝依附元件，但 Node.js 執行階段仍會執行應用程式。專案必須包含 package.json 檔案。如要進一步瞭解設定需求，請參閱 Buildpacks 說明文件中的「建構 Node.js 應用程式」。

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

部署完成後，您可以在函式建構程序中執行自訂建構步驟，方法是在 package.json 檔案中新增 gcp-build 指令碼。

執行此指令碼時，package.json 檔案中的 dependencies 和 devDependencies 欄位的依附元件為可用狀態。執行自訂建構步驟後，Cloud Run functions 只會安裝 package.json 檔案 dependencies 欄位中宣告的實際依附元件，以移除並重新產生 node_modules 資料夾。

如果 package.json 中沒有 gcp-build 指令碼，Cloud Run functions 只會安裝實際依附元件。

使用系統套件

Node.js 執行階段在執行環境中還包含多個系統套件。

納入本機 Node.js 模組

您也可以將本機 Node.js 模組納入函式。如要這麼做，請使用 file: 前置字元，在 package.json 中宣告模組。在下列範例中，mymodule 是指模組名稱，mymoduledir 則是包含模組的目錄：

  {
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

這個本機模組的程式碼應儲存在函式根目錄的 node_modules 資料夾以外的位置。

注意：如果使用 gcloud 指令列工具進行部署，gcloud 會自動在函式的目錄中建立 .gcloudignore 檔案。根據預設，node_modules 資料夾會新增至這個 .gcloudignore，且不會做為部署作業的一部分上傳。手動上傳程式碼 .zip 檔案時，無須將 node_modules 資料夾納入 .zip 檔案，因為即使沒有 node_modules 資料夾，您也能成功部署函式。

載入 Node.js 模組

使用 Node.js require() 函式載入任何您已安裝的 Node.js 模組。您也可以使用 require() 函式匯入您與函式一起部署的本機檔案。

使用私人模組

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

Artifact Registry 的私人模組

Artifact Registry Node.js 套件存放區可託管函式的私人模組。部署 Cloud Run functions 函式時，建構程序會自動為 Cloud Build 服務帳戶產生 Artifact Registry 憑證。您只需在 .npmrc 中列出 Artifact Registry 存放區，不用產生額外憑證。例如：

@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 v1 套件管理工具。如果您使用 Yarn v2 以上版本，只需在 .yarnrc.yml 中列出 Artifact Registry 存放區，無須提供額外憑證。例如：

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

其他存放區的私人模組

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

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

注意：如果您使用任何自訂權限 (例如 VPC 必要的權限)，請務必明確允許函式存取目標私人存放區。

檔案格式

如果您使用 .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 私人模組教學課程。

使用複製的依附元件建構函式

複製的依附元件是指來源直接納入原始碼套件，並與您的程式碼一併重建的依附元件。您可以使用 GOOGLE_VENDOR_NPM_DEPENDENCIES 建構環境變數，建立複製的 Node.js 依附元件，並在部署期間略過安裝這些依附元件。

複製依附元件的必要條件

1. 請確認您已建立可正常運作的函式，且 package.json 檔案中定義了所有要複製的依附元件。

2. 執行下方指令，在本機安裝這些依附元件：

       npm install
   

3. 從工作目錄的 .gcloudignore 檔案中移除 node_modules。

4. 部署函式，並確保本機 Node.js 版本與部署期間指定的版本相同。

5. 使用下方指令部署函式和複製的依附元件：

     gcloud run deploy SERVICE \
       --source . \
       --function FUNCTION_ENTRY_POINT \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   取代：

   • SERVICE：要部署的 Cloud Run function 名稱
   • FUNCTION_ENTRY_POINT：原始碼中函式的進入點。

如果您在 package.json 檔案中指定 npm 引擎，系統會在建構時下載指定版本的 npm。如要禁止這項行為，請從 package.json 檔案中移除。