指定 Node.js 依赖项

函数可以使用外部 Node.js 模块以及本地数据。Node.js 中的依赖项可通过 npm 进行管理，并在名为 package.json 的元数据文件中表示。Cloud Functions Node.js 运行时支持使用 npm、yarn 或 pnpm 进行安装。

要为您的函数指定依赖项，请将依赖项添加到 package.json 文件中。

注意：如果在项目中发现 package-lock.json、yarn.lock 或 pnpm-lock.yaml 文件，则在使用 npm ci、yarn install 或 pnpm install 安装依赖项时会遵循该 lock 文件。

在此示例中，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 框架是所有函数必需的依赖项。虽然 Cloud Functions 会在创建函数时代表您安装该框架，但为清楚起见，我们建议您将其添加为显式依赖项。

如果函数依赖于专用依赖项，我们建议您将 functions-framework 镜像到您的私有注册表。将镜像的 functions-framework 作为依赖项添加到函数中，以避免从公共互联网安装软件包。

使用 npm 在本地安装 Node.js 模块

要在本地安装 Node.js 模块，最简单的方法是在包含您的 Cloud Functions 函数的文件夹中使用 npm install 命令。例如，以下命令将添加 uuid 模块：

npm install uuid

此命令会执行两个步骤：

1. 将该模块的最新版本作为依赖项添加到 package.json 文件中。这一点很重要：Cloud Functions 仅安装已在您的 package.json 文件中声明的模块。
2. 将该模块下载到 node_modules 目录中。这样您便可以在本地开发时使用该模块。

如果您的机器上未安装 npm，请获取 npm。

注意：npm 软件包可用于各种 Google Cloud 产品。请点击此处，查看相关列表。

配置部署依赖项

您可以为 NPM、Yarn 或 Pnpm 安装生产依赖项：

NPM

部署您的函数后，Cloud Functions 会使用 npm install 命令安装 package.json 文件中声明的依赖项。

npm install --production

Yarn

在 Node.js 8 运行时及更高版本中，如果存在 yarn.lock 文件，则 Cloud Functions 会改用 yarn install 命令：

yarn install --production

Pnpm

在 Node.js 8 运行时及更高版本中，如果存在 pnpm-lock.yaml 文件，则 Cloud Functions 会改用 pnpm install 命令：

pnpm install

注意：系统不会安装在子目录中声明的依赖项。如果您使用的是 monorepo，则可以在部署期间执行自定义构建脚本来安装这些依赖项。

在部署期间执行自定义构建步骤

部署后，在函数构建过程中，您可以通过在 package.json 文件中添加 gcp-build 脚本来执行自定义构建步骤。

执行此脚本时，可以使用 package.json 文件的 dependencies 和 devDependencies 字段中的依赖项。执行自定义构建步骤后，Cloud Functions 仅安装 package.json 文件的 dependencies 字段中声明的生产依赖项，以移除并重新生成 node_modules 文件夹。

如果 package.json 中没有 gcp-build 脚本，则 Cloud Functions 仅安装生产依赖项。

使用系统软件包

Node.js 运行时还会在执行环境中添加多个系统软件包。如果您的函数使用的依赖项需要未列出的软件包，您可以请求添加软件包。

注意：您还可以使用 Functions 框架将容器化版本的 Node.js Cloud Functions 部署到 Cloud Run。

包括本地 Node.js 模块

您还可以将本地 Node.js 模块作为函数的一部分。要实现此目的，您可在 package.json 中使用 file: 前缀声明相关模块。在以下示例中，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 v2 或更高版本作为软件包管理器，则此文件的名称为 .yarnrc.yml。

Artifact Registry 中的专用模块

Artifact Registry Node.js 软件包代码库可以托管您的函数的专用模块。部署 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 文件，因为该文件可能会延长函数的部署时间。

注意：如果您使用的是任何自定义权限（例如 VPC 所需的权限），请确保您明确允许您的函数访问目标私有代码库。

文件格式

如果您使用 .npmrc 文件设置自定义身份验证令牌，则应包含下面所示的一行内容。

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

您需要将其中的：

• REGISTRY_DOMAIN：您的私有 npm 注册表的域名。如果您的代码库由 npmjs.org 托管，请将此字段设置为 registry.npmjs.org。

• AUTH_TOKEN：npm 注册表的授权令牌。它可以是令牌的字面量文本值或文本字符串 ${NPM_TOKEN}（npm 会将其替换为环境中的实际令牌值）。

  您可以设置 $NPM_TOKEN 环境变量，并将 --set-build-env-vars 参数传递给 gcloud functions deploy 命令。 如需详细了解 NPM 身份验证令牌，请参阅有关专用模块的 NPM 教程。

使用 vendored 依赖项构建函数

Vendored 依赖项是其源代码直接包含在源代码包中并与您自己的代码一起重新构建的项目。您可以使用 GOOGLE_VENDOR_NPM_DEPENDENCIES 构建环境变量，创建 vendored Node.js 依赖项并在部署期间跳过其安装。

vendored 依赖项的前提条件

1. 确保您拥有有效的函数，其中包含您希望在 package.json 文件中定义 vendor 的所有依赖项。

2. 通过运行以下命令在本地安装这些依赖项

       npm install
   

3. 从工作目录的 .gcloudignore 文件中移除 node_modules。

4. 部署函数，确保本地 Node.js 版本与您在部署期间指定的版本相同。

5. 使用以下命令部署函数和 vendored 依赖项：

     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 版本相同

Functions 框架软件包是函数必需的依赖项。为加快构建速度，我们建议 vendoring 此软件包。否则，其会在您的函数构建时被下载并安装。

如果您在 package.json 文件中指定了 npm 引擎，则系统会在构建时下载指定的 npm 版本。如需抑制此行为，请从 package.json 文件中将其移除。