在 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 函式會移除並重新產生 node_modules 資料夾，方法是只安裝 package.json 檔案 dependencies 欄位所宣告的實際依附元件。

如果 package.json 中沒有 gcp-build 指令碼，Cloud Run 函式只會安裝正式版依附元件。

使用系統套件

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 資料夾，即使沒有 node_modules 資料夾，您也能順利部署函式。

載入 Node.js 模組

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

使用私人模組

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

Artifact Registry 中的私人模組

Artifact Registry Node.js 套件存放區可代管函式的私人模組。部署 Cloud Run 函式時，建構程序會自動為 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 2 以上版本，只需在 .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 檔案中移除該行為。