Node.js 运行时

注意：某些 Node.js 运行时已达到支持终止期限。在支持终止日期之后，您无法重新部署使用这类运行时的版本。我们建议您升级应用以使用最新版本的 Node.js。

Node.js 运行时是负责安装应用代码和依赖项，然后在柔性环境中运行该应用的软件栈。

Node.js 版本

Node.js 22 使用 buildpacks。默认 Node.js 引擎使用最新 LTS 版本。如需查看支持的 Node.js 版本及其对应 Ubuntu 版本的完整列表，请参阅运行时支持时间表。

如需使用支持的 Node.js 版本，您必须：

• 安装 gcloud CLI 420.0.0 版或更高版本。您可以通过运行 gcloud components update 命令来更新 CLI 工具。如需查看已安装的版本，请运行 gcloud version 命令。

• 将 runtime_config 和 operating_system 设置添加到 app.yaml 文件中以指定操作系统。

• （可选）通过以下方式指定版本：

  • 在 app.yaml 文件中添加 runtime_version 设置。默认情况下，如果未指定 runtime_version 设置，则使用最新 Node.js 版本。例如：

    • 如需在 Ubuntu 22 上指定 Node.js 22，请运行以下命令：

        runtime: nodejs
        env: flex
      
        runtime_config:
            operating_system: "ubuntu22"
            runtime_version: "22"
      

    • 如需在 Ubuntu 22 上指定受支持的最新 Node.js 版本，请运行以下命令：

        runtime: nodejs
        env: flex
      
        runtime_config:
            operating_system: "ubuntu22"
      

      runtime_version 设置支持 semver。

  • 使用 engines 字段在应用的 package.json 文件中添加受支持的最新 Node.js 版本。如果您使用 engines 字段指定了版本，则 runtime_version 设置优先。为防止出现意外中断，建议您在 engines 字段中指定 Node.js 版本，以及 runtime_version。例如：

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

    engines.node 属性可以是 semver 范围。 如果您指定此属性，则运行时会下载并安装与 semver 范围匹配的最新版本 Node.js。如果未找到匹配项，则应用将无法部署，并且运行时将返回错误。

过往运行时版本

警告：Node.js 16 版及更低版本已达到支持终止期限。App Engine 会阻止您使用已达到支持终止期限的运行时部署应用。我们建议您迁移应用以使用支持的 Node.js 版本或使用自定义运行时。

对于 Node.js 运行时 16 及更早版本，请在应用的 package.json 文件中使用 engines 字段指定版本。

以下示例将运行时配置为使用 Node 9 版本：

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

engines.node 属性可以是 semver 范围。 如果您指定此属性，则运行时会下载并安装与 semver 范围匹配的最新版本 Node.js。如果未找到匹配项，则应用将无法部署，并且运行时将返回错误消息。

对其他 Node.js 运行时的支持

如果您需要使用不受支持的 Node.js 版本，可以创建自定义运行时，并选择带有所需 Node.js 版本的有效基础映像。

对于 Google 提供的基础映像或 Docker Node.js 基础映像，请参阅构建自定义运行时。

软件包管理器

在部署期间，运行时使用 npm 或 yarn 或 Pnpm 软件包管理器来安装依赖项并启动应用。软件包管理器是使用以下逻辑进行设置的：

• 默认软件包管理器为 npm。
• 如果应用的根目录中存在 yarn.lock 文件，运行时会改为使用 yarn 软件包管理器。
• 仅对于 Node.js 18 版及更高版本，如果应用根目录中存在 pnpm-lock.yaml 文件，则运行时会改用 Pnpm 软件包管理系统。
• 如果 package-lock.json 以及 yarn.lock 或 pnpm-lock.yaml 都存在，则部署将失败并报错。如果您需要 package-lock.json 文件，则必须在 app.yaml 文件的 skip_files 部分中指定其他软件包管理器文件，以解析要使用哪个软件包管理器。

软件包管理器版本

运行时映像旨在使用 最新的 Node.js LTS 版本中提供的最新 yarn 版本和 npm 版本。

您可以使用 engines 字段在应用的 package.json 文件中指定要使用的其他软件包管理系统版本。在这种情况下，运行时将确保用于部署的软件包管理系统具有与 engines 字段中列出的规范相匹配的版本。

如果同时指定了 yarn 和 npm 版本规范，则只会根据需要更新用于部署的软件包管理器。如果实际上未使用软件包管理器来部署应用，则不会安装自定义版本的软件包管理器，这样就节省了部署时间。

以下示例将运行时配置为使用自定义版本的 npm：

{
  "engines": {
    "npm": "5.x"
  }
}

下一个示例将运行时配置为使用自定义版本的 yarn：

{
  "engines": {
    "yarn": ">=1.0.0 <2.0.0"
  }
}

engines.npm 和 engines.yarn 属性都可以是 semver 范围。

依赖项

在部署期间，运行时将使用 npm 或 yarn 软件包管理器，通过运行 npm install 或 yarn install 来安装依赖项。请参阅软件包管理器部分，详细了解运行时如何选择要使用的软件包管理器。

此外，如需详细了解如何在 Google App Engine 上管理 Node.js 软件包，请参阅使用 Node.js 库。

为了支持使用需要原生扩展的 Node.js 软件包，Docker 映像中预先安装了以下Ubuntu 软件包。

• build-essential
• ca-certificates
• curl
• git
• imagemagick
• libkrb5-dev
• netbase
• python

如果您的应用需要其他操作系统级依赖项，您将需要使用基于此运行时的自定义运行时来安装相应的软件包。

NPM 构建脚本

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

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

• 在 package.json 文件中添加具有空值的 gcp-build 脚本："gcp-build":""。

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

  build_env_variables:
    GOOGLE_NODE_RUN_SCRIPTS: ''
  

如需详细了解如何指定构建环境变量，请参阅 app.yaml 文件中的 build_env_variables 部分。

应用启动

运行时通过使用 npm start（使用 package.json 中指定的命令）启动应用。例如：

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

您的启动脚本应该启动一个网络服务器以响应 PORT 环境变量所指定的端口（通常为 8080）上的 HTTP 请求。

扩展运行时

您可以使用自定义运行时为 App Engine 柔性环境中运行的 Node.js 应用添加额外功能。如需配置自定义运行时，请将 app.yaml 文件中的以下行：

runtime: nodejs

替换为以下行：

runtime: custom

您还必须在 app.yaml 文件所在的目录中添加 Dockerfile 和 .dockerignore 文件。

请参阅自定义运行时文档，了解如何在自定义运行时中定义 Dockerfile。

HTTPS 和转发代理

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

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

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

要了解如何强制执行 HTTPS 连接，请参阅请求的处理方式。

环境变量

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

环境变量	说明
GAE_INSTANCE	当前实例的名称。
GAE_MEMORY_MB	可供应用进程使用的内存量。
GAE_SERVICE	在应用的 app.yaml 文件中指定的服务名称，如果未指定服务名称，则设置为 default。
GAE_VERSION	当前应用的版本标签。
GOOGLE_CLOUD_PROJECT	与您的应用关联的项目 ID，可在 Google Cloud 控制台中查看
NODE_ENV	部署应用时，该值为 production。
PORT	将接收 HTTP 请求的端口。设置为 8080。

您可以使用 app.yaml 设置其他环境变量。

元数据服务器

应用的每个实例都可以使用 Compute Engine 元数据服务器来查询有关实例的信息，包括实例的主机名、外部 IP 地址、实例 ID、自定义元数据和服务账号信息。App Engine 不支持为每个实例设置自定义元数据，但您可以设置项目范围的自定义元数据并从 App Engine 和 Compute Engine 实例中读取这些元数据。

此示例函数使用元数据服务器来获取实例的外部 IP 地址。

const express = require('express');
const fetch = require('node-fetch');

const app = express();
app.enable('trust proxy');

const METADATA_NETWORK_INTERFACE_URL =
  'http://metadata/computeMetadata/v1/' +
  '/instance/network-interfaces/0/access-configs/0/external-ip';

const getExternalIp = async () => {
  const options = {
    headers: {
      'Metadata-Flavor': 'Google',
    },
    json: true,
  };

  try {
    const response = await fetch(METADATA_NETWORK_INTERFACE_URL, options);
    const ip = await response.json();
    return ip;
  } catch (err) {
    console.log('Error while talking to metadata server, assuming localhost');
    return 'localhost';
  }
};

app.get('/', async (req, res, next) => {
  try {
    const externalIp = await getExternalIp();
    res.status(200).send(`External IP: ${externalIp}`).end();
  } catch (err) {
    next(err);
  }
});

const PORT = parseInt(process.env.PORT) || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});