在 Node.js 中指定依附元件

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

如要為函式指定依附元件，請將其新增到 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')}!`);
});

函式架構是所有函式的必要依附元件。雖然 Cloud Run functions 會在建立函式時代您安裝，但我們建議您將其納入明確的依附元件，以確保清楚明瞭。

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

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

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

npm install uuid

這項指令結合了兩個步驟：

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

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

注意： npm 套件適用於各種 Google Cloud 產品。請參閱這份清單。

設定部署作業依附元件

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

NPM

部署函式時，Cloud Run functions 會使用 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 執行階段在執行環境中還包含多個系統套件。如果您的函式使用的依附元件，需要並未列出的系統套件，您可以要求套件。

注意： 您也可以使用 Functions Framework，將 Node.js Cloud Run 函式的容器化版本部署至 Cloud Run。

包含本機 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 v2 以上版本做為套件管理員，這個檔案會命名為 .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 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 functions deploy FUNCTION_NAME \
       --runtime RUNTIME_NAME \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   取代：

   • ：要部署的 Cloud Run functions 函式名稱FUNCTION_NAME
   • RUNTIME_NAME：用於執行已部署函式的 Node.js 執行階段名稱。這必須與您在本機開發環境中使用的 Node.js 版本相同

函式需要 Functions 架構套件做為依附元件。如要加快建構速度，建議您供應這個套件。否則，系統會在建構函式時下載並安裝。

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