Node.js 运行时环境

Node.js 运行时是负责安装 Web 服务代码及其依赖项并运行服务的软件栈。

适用于 App Engine 标准环境的 Node.js 运行时环境在 app.yaml 文件中进行声明：

runtime: nodejsVERSION

其中 VERSION 是 Node.js MAJOR 版本号。例如，如需使用最新的 Node.js 版本 Node.js 22，请指定 22。

如需了解其他受支持的 Node.js 版本以及 Node.js 版本对应的 Ubuntu 版本，请参阅运行时支持时间表。

Node.js 版本

Node.js 运行时使用 app.yaml 文件中指定的版本的最新稳定版。App Engine 会自动更新到新的补丁和次要发布版本，但不会自动更新主要版本。

例如，您的应用可能部署在 Node.js 10.9.4，并在日后自动更新到 10.10.0 版，但不会自动更新到 Node.js 12.x.x。

由于次要版本和补丁版本会自动更新（如果存在），因此 package.json 文件中的 engines.node 属性只能指定主要版本，并与 app.yaml 文件中指定的 Node.js 版本兼容。

例如，对于 22：

• 22.x.x
• ^22.0.0
• ~22
• >=6

如果您在 package.json 文件中指定了不兼容的 Node.js 版本，则部署将失败并显示错误消息。

依赖项

在部署期间，运行时会使用 npm install 命令安装依赖项。运行时还支持 Yarn (yarn.lock) 和 Pnpm (pnpm-lock.yaml) 软件包管理器。如需了解详情，请参阅指定依赖项。由于运行时会执行全新安装，因此您无需上传 node_modules 文件夹。

为了支持需要原生扩展程序的 Node.js 软件包，运行时包含系统软件包，以便您能够使用 ImageMagick、FFmpeg 和 Chrome headless 等工具。如需查看完整的软件包列表，请参阅包含的系统软件包。如需提交软件包请求，请在问题跟踪器中提交问题。

NPM 构建脚本

默认情况下，如果 package.json 中检测到 build 脚本，则 Node.js 运行时会执行 npm run build。如果您需要在启动应用之前对构建步骤进行额外的控制，则可以通过向 package.json 文件添加 gcp-build 脚本来提供自定义构建步骤。

如需阻止构建运行 npm run build 脚本，您必须执行以下操作之一：

• 在 package.json 文件中添加具有空值的 gcp-build 脚本："gcp-build":""。如需详细了解如何配置 package.json，请参阅 Node.js Buildpack 配置。

• 在 app.yaml 文件中添加具有空值的 GOOGLE_NODE_RUN_SCRIPTS 构建环境变量。

  build_env_variables:
    GOOGLE_NODE_RUN_SCRIPTS: ''
  

应用启动

默认情况下，运行时通过运行 node server.js 来启动应用。 如果您在 package.json 文件中指定 start 脚本，则运行时会运行指定的启动脚本。例如：

"scripts": {
  "start": "node app.js"
}

为了让您的应用接收 HTTP 请求，start 脚本应启动一个 Web 服务器，该服务器侦听主机的 0.0.0.0 和 PORT 环境变量指定的端口，该端口在 Node.js 中可通过 process.env.PORT 访问。

为了获得最佳性能，start 脚本应该是轻量级的，并且不包括构建步骤，因为每次创建应用的新实例时该脚本都会运行。

您可以通过在 app.yaml 的 entrypoint 字段中指定脚本来替换此行为。运行时会使用您在 entrypoint 中指定的命令启动应用，而不是运行 node server.js 或启动脚本。

环境变量

以下环境变量由运行时设置：

您可以在 app.yaml 文件中定义其他环境变量，但不能替换上述值（NODE_ENV 除外）。

HTTPS 和转发代理

App Engine 在负载均衡器上终止 HTTPS 连接，并将请求转发到您的应用。某些应用需要确定原始请求 IP 地址和协议。用户的 IP 地址可在标准 X-Forwarded-For 标头中获取。对于需要此信息的应用，应将其 Web 框架配置为信任代理。

在 Express.js 框架中，使用 trust proxy 设置：

app.set('trust proxy', true);

请注意，将 trust proxy 设置为 true 可能会使 req.ip 属性暴露于 IP 仿冒漏洞。

文件系统

运行时包含一个完整的文件系统。该文件系统是只读的，但位置 /tmp 除外（该位置是在 App Engine 实例的 RAM 中存储数据的虚拟磁盘）。

元数据服务器

应用的每个实例都可以使用 App Engine 元数据服务器来查询有关实例和项目的信息。

您可以通过以下端点访问元数据服务器：

• http://metadata
• http://metadata.google.internal

发送到元数据服务器的请求必须包含请求标头 Metadata-Flavor: Google。此标头表明请求是为了检索元数据值而发出的。

下表列出了您可以针对特定元数据发出 HTTP 请求的端点：

例如，要检索您的项目 ID，请向 http://metadata.google.internal/computeMetadata/v1/project/project-id 发送请求。