處理依附元件


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

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

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

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

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

JavaScript

const escapeHtml = require('escape-html');

// Return a greeting with the input HTML-escaped.
exports.hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

TypeScript

import * as escapeHtml from 'escape-html';

// Return a greeting with the input HTML-escaped.
export let hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
}

納入本機 Node.js 模組

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

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

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

TypeScript 適用的其他步驟

使用含有類型資訊的程式庫時，TypeScript 最有幫助。這可讓 TypeScript 擷取語法錯誤，並讓編輯器提供更完善的自動完成建議。firebase-admin 和 firebase-functions 等部分程式庫會隨附 TypeScript 定義。

許多程式庫並未提供自己的 TypeScript 定義。DefinitelyTyped 專案為最熱門的節點程式庫提供社群維護的定義。DefinitelyTyped 會在相同的 NPM 套件名稱下發布這些定義，但位於「@types」組織內。舉例來說，您可以使用以下方式安裝 uuid 程式庫的類型資訊：

npm install @types/uuid

隨著您對 TypeScript 越來越熟悉，您可能會發現自己會同時使用這兩種安裝方式：

npm install uuid @types/uuid

類型依附元件應與程式庫依附元件相同。舉例來說，您不應將 uuid 儲存為一般依附元件，而將 @types/uuid 儲存為開發依附元件或同級依附元件。

載入 Node.js 模組

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

如果您要在 TypeScript 中編寫函式，請以相同方式使用 import 陳述式載入任何已安裝的 Node.js 模組。

使用私人模組

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

Artifact Registry 中的私人模組

Artifact Registry Node.js 套件存放區可代管函式的私人模組。部署 Google Cloud 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 2 以上版本，只需在 .yarnrc.yml 中列出 Artifact Registry 存放區，無須額外提供憑證。例如：

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

其他存放區的私人模組

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

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

檔案格式

如果您使用 .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 functions deploy FUNCTION_NAME \
    --runtime RUNTIME_NAME \
    --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true

    取代：

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

函式架構套件是函式所需的依附元件。為加快建構速度，建議您將這個套件轉為供應商。如果沒有，系統會在建構函式時下載及安裝。

如果您在 package.json 檔案中指定 npm 引擎，系統會在建構期間下載指定的 npm 版本。如要抑制這種行為，請從 package.json 檔案中移除該行為。