构建 Node.js 应用

指定 Node.js 版本

Buildpack 项目支持 Node.js 的当前和活跃 LTS 版本。旧版 Node.js 也可以使用,但项目可能不会对旧版本主动进行维护。

使用 package.json

您可以通过在 package.json 中配置 engines.node 字段,在部署期间指定应用的 Node.js 版本。如需在部署应用时将 Buildpack 配置为使用最新版本的 Node.js v16,您可以在 package.json 中使用以下值:

"engines": {
  "node": "16.x.x"
}

使用 GOOGLE_NODEJS_VERSION

还可以通过 GOOGLE_NODEJS_VERSION 环境变量指定 Node.js 版本。如果同时设置了这两个配置,则 GOOGLE_NODEJS_VERSION 值优先于 engines.node 属性。如果未提供值,则使用最新 LTS 版本的 Node.js。

如需在部署应用时将 Buildpack 配置为使用 Node.js 16,请执行以下命令:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=16.x.x

您还可以使用 project.toml 项目描述符对环境变量以及项目文件进行编码。请参阅使用环境变量构建应用中的说明。

提示

  • engines.node 字段可以接受 semver 限制条件。用于 Node.js Buildpack 的特定库是 Masterminds/semver
  • 避免在 engines.node 中使用大于号 (>) 说明符
  • 将应用部署到 App Engine 标准环境时,engines.node 属性应与 app.yaml 中指定的运行时兼容
  • 如需查看有关 package.jsonengines.node 配置选项的更多文档,请参阅引擎主题下的官方 NPM 文档
  • 将函数部署到 Cloud Run 函数时,engines.node 属性应与用于部署函数的运行时兼容

安装依赖项

使用 NPM

  • NPM 是默认的软件包管理系统。
  • 尽可能使用 package-lock.json 来提高缓存性能。
  • 默认仅安装生产依赖项。
  • 您可以使用 package.json 文件中的 engines.npm 字段指定 npm 版本部分。

使用 Yarn

  • 如果您在项目中添加 yarn.lock 文件,则系统会改用 Yarn。
  • 您可以在 package.json 文件的 engines.yarn 字段中指定要使用的 Yarn 版本。
  • 如果您的项目包含 .yarn/cache,则支持 Yarn2 PnP 模式。

使用 Pnpm

  • 如果您在项目中添加 pnpm-lock.yaml 文件,则系统会改用 Pnpm。
  • 您可以在 package.json 文件的 engines.pnpm 字段中指定 pnpm 的版本。
  • 如需查看有效示例,请参阅 sample-node-pnpm 应用。

使用专用模块

您可以使用专用 npm 模块,方法是在函数目录下的 .npmrc 文件中提供向注册表进行身份验证的设置。如果您使用 Yarn 版本 2 或更高版本作为软件包管理系统,则此文件名为 .yarnrc.yml

Artifact Registry 中的专用模块

Artifact Registry Node.js 软件包代码库可以托管您的函数的专用模块。部署 Buildpack 函数时,构建流程会自动为 Cloud Build 服务账号生成 Artifact Registry 凭据。使用 NPM 或 Yarn 版本 1 时,您只需在 .npmrc 文件中列出 Artifact Registry 代码库。例如,使用 NPM 或 Yarn 版本 1 时:

@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 版本 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 命令会将其替换为环境中的实际令牌值)。

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

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

默认情况下,如果 package.json 文件中指定了脚本,则系统会运行 npm run build。不过,您也可以改为指定自定义构建步骤来替换默认行为,并仅在构建期间运行您需要的脚本。您可以在 package.json 文件中使用 GOOGLE_NODE_RUN_SCRIPTS 环境变量或 gcp-build 来控制构建步骤。

您只能使用一种方法。请注意,GOOGLE_NODE_RUN_SCRIPTS 环境变量优先,并替换为 package.json 中的 gcp-build 指定的任何值。

默认情况下,当您配置自定义构建步骤时,系统会先安装 package.json 文件中的 dependenciesdevDependencies,然后再执行任何脚本或命令。如需替换默认行为,您可以使用 NODE_ENV 环境变量。

使用 GOOGLE_NODE_RUN_SCRIPTS

您可以将 GOOGLE_NODE_RUN_SCRIPTS 环境变量传递给构建来控制运行的脚本。您可以指定一个或多个脚本,也可以改为传递空环境变量来阻止默认行为运行,例如 GOOGLE_NODE_RUN_SCRIPTS=。如需了解完整详情,请参阅环境变量

使用 package.json

package.json 文件中添加 gcp-build 只会运行 npm run gcp-build,这意味着它会替换默认行为。您可以指定一个或多个命令,也可以改为指定空字符串来阻止任何命令运行,例如 "gcp-build":""

"scripts": {
  ...
  "gcp-build": "npm run lint && npm run build"
  ...
}

应用入口点

Node.js Buildpack 执行 package.jsonscripts.start 字段中指定的命令。如果未设置 scripts.start,Buildpack 会运行 npm start

我们建议您使用 Procfile,因为它会从路径中提取 npmyarn

环境变量

您可以设置环境变量来配置容器映像的 build

Node.js Buildpack 支持使用以下环境变量来自定义容器。

NPM_CONFIG_<key>

请参阅文档

示例NPM_CONFIG_FLAG=value 会将 -flag=value 传递给 npm 命令。

NODE_ENV

在构建期间指定开发环境;为 npm install 设置。

示例NODE_ENV=development 会安装 package.json 中指定的 dependenciesdevDependencies

GOOGLE_NODE_RUN_SCRIPTS

指定在安装依赖项后要运行的 package.json 中的 npm 脚本的有序列表。该列表必须以英文逗号分隔,并按列出每个脚本的顺序运行。

如果您指定 GOOGLE_NODE_RUN_SCRIPTS,则系统仅会运行您列出的脚本。例如,如果您想要阻止默认 npm run build 运行,则可以指定环境变量而不指定值。

示例

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build 运行 npm run lint,然后运行 npm run build
  • GOOGLE_NODE_RUN_SCRIPTS= 不运行任何脚本。