在 Node.js 中指定依附元件

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

Node.js Functions Framework 是所有函式都必須具備的依附元件。雖然 Cloud Run 函式會在建立函式時為您安裝，但我們建議您將其納入明確的依附元件，以確保清楚明瞭。

如果函式依附於私有依附元件，建議您將 functions-framework 鏡像到私有登錄檔。將鏡像 functions-framework 做為函式的依附元件，避免從公開網際網路安裝套件。

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

注意： 如果系統在專案中找到 package-lock.json、yarn.lock 或 pnpm-lock.yaml 檔案，使用 npm ci、yarn install 或 pnpm install 安裝依附元件時，系統會遵守該鎖定檔案。

在這個範例中，依附元件會列在 package.json 檔案中：

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

然後，依附元件會匯入函式中：

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 函式只會安裝 package.json 檔案中宣告的模組。
2. 它會將模組下載到 node_modules 目錄中，讓您在本機開發時使用。

如果您的電腦上沒有安裝 npm，請取得 npm。

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

設定部署作業依附元件

您可以安裝 NPM、Yarn 或 Pnpm 的正式版依附元件：

NPM

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

npm install --production

紗線

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

yarn install --production

Pnpm

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

pnpm install

注意： 系統不會安裝在子目錄中宣告的依附元件。如果您使用單一存放區，可能需要在部署期間執行自訂建構指令碼，以安裝這些依附元件。

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

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

執行此指令碼時，package.json 檔案中的 dependencies 和 devDependencies 欄位的依附元件為可用狀態。執行自訂建構步驟後，Cloud Run 函式只會安裝 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，且不會做為部署的一部分上傳。手動上傳程式碼時，無須將 node_modules 資料夾納入 ZIP 檔案，因為即使沒有 node_modules 資料夾，您也能成功部署函式。

載入 Node.js 模組

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

使用私人模組

如要使用私人 npm 模組，請在函式目錄的 .npmrc 檔案中提供驗證登錄檔的設定。如果您使用 Yarn 第 2 版以上做為套件管理員，這個檔案會命名為 .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 會將其替換為環境中的實際權杖值。

  您可以使用 --set-build-env-vars 引數，為 gcloud functions deploy 指令設定 $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_ENTRY_POINT：來源程式碼中函式的進入點。

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