指定 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.json
中engines.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
文件中的 dependencies
和 devDependencies
,然后再执行任何脚本或命令。如需替换默认行为,您可以使用 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.json
的 scripts.start
字段中指定的命令。如果未设置 scripts.start
,Buildpack 会运行 npm start
。
我们建议您使用 Procfile,因为它会从路径中提取 npm
或 yarn
。
环境变量
Node.js Buildpack 支持使用以下环境变量来自定义容器。
NPM_CONFIG_<key>
请参阅文档。
示例:NPM_CONFIG_FLAG=value
会将 -flag=value
传递给 npm
命令。
NODE_ENV
在构建期间指定开发环境;为 npm install
设置。
示例:NODE_ENV=development
会安装 package.json
中指定的 dependencies
和 devDependencies
。
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=
不运行任何脚本。