在 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')}!`);
});

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

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

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

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

npm install uuid

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

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

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

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

設定部署作業依附元件

您可以安裝 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

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

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

部署完成後，您可以在函式建構程序中執行自訂建構步驟，方法是在 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 執行階段在執行環境中還包含多個系統套件。如果您函式使用的依附元件需要未列出的系統套件，您可以要求套件。

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

納入本機 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 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 檔案中移除。