處理依附元件

選取語言： Node.js Python

Cloud Functions 函式可使用外部模組和本機依附元件。指定及管理依附元件的方式取決於執行階段語言。

Node.js

函式可使用外部 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 onRequest = require("firebase-functions/https");
const escapeHtml = require("escape-html");

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

TypeScript

import { onRequest } from "firebase-functions/https";
import * as escapeHtml from "escape-html";

// Return a greeting with the input HTML-escaped.
export let hello = 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 v2 以上版本做為套件管理工具，這個檔案會命名為 .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 v2 以上版本，只需在 .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 會將其替換為環境中的實際權杖值。

    您可以使用 gcloud functions deploy 指令的 --set-build-env-vars 引數，設定 $NPM_TOKEN 環境變數。如要進一步瞭解 NPM 驗證權杖，請參閱 NPM 私人模組教學課程。

Python

您可以透過兩種方式，為以 Python 編寫的 Cloud Functions 指定依附元件：使用 pip 套件管理工具的 requirements.txt 檔案，或與您的函式一起封裝本機依附元件。

系統不支援使用 Pipfile/Pipfile.lock 標準來指定依附元件，請勿將這類檔案納入專案中。

透過 pip 指定依附元件

Python 中的依附元件是透過 pip 管理，並以稱為 requirements.txt 的中繼資料檔案表示。這個檔案必須與包含函式程式碼的 main.py 檔案位在同一目錄。

部署或重新部署函式時，Cloud Functions 會使用 pip 下載並安裝 requirements.txt 檔案中宣告的最新版依附元件。requirements.txt 檔案中一行代表一個套件，每行都包含套件名稱以及要求的版本。詳情請參閱 requirements.txt 參考資料。

為避免建構過程受到依附元件版本變更的影響，建議將依附元件套件固定於特定版本。

以下是 requirements.txt 檔案範例：

functions-framework
requests==2.20.0
numpy

封裝本機依附元件

您也可以將依附元件與函式一併封裝及部署。如果無法透過 pip 套件管理工具使用依附元件，或者 Cloud Functions 環境的網路連線能力受限，此方法就非常實用。

例如，您可以採用如下所示目錄結構：

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

然後使用下列 import 陳述式，照常從 localpackage 匯入程式碼。

# Code in main.py
from localpackage import script

請注意，這個方法不會執行任何 setup.py 檔案。含有這些檔案的套件仍可搭配組合，但可能無法在 Cloud Functions 上正常執行。