Node.js 執行階段

Node.js 執行階段是一種軟體堆疊，用於安裝應用程式的程式碼和依附元件，然後在彈性環境中執行該應用程式。

Node.js 版本

Node.js 24 (預先發布版) 使用建構套件。預設的 Node.js 引擎使用 LTS 最新版。如需支援的 Node.js 版本完整清單，以及對應的 Ubuntu 版本，請參閱「執行階段支援時間表」。

如要使用支援的 Node.js 版本，請務必：

  • 安裝 gcloud CLI 420.0.0 以上版本。您可以執行 gcloud components update 指令，更新 CLI 工具。如要查看已安裝的版本，請執行 gcloud version 指令。

  • 在 app.yaml 檔案中加入 runtime_config 和 operating_system 設定，指定作業系統。

  • 您可以視需要指定版本，方法如下：

    • 在 app.yaml 檔案中新增 runtime_version 設定。如未指定 runtime_version 設定，系統預設會使用最新 Node.js 版本。例如：

      • 如要在 Ubuntu 24 上指定 Node.js 24 (預覽版)：

          runtime: nodejs
  env: flex

  runtime_config:
      operating_system: "ubuntu24"
      runtime_version: "24"

      • 如要在 Ubuntu 24 上指定最新支援的 Node.js 版本，請執行下列操作：

          runtime: nodejs
  env: flex

  runtime_config:
      operating_system: "ubuntu24"

        runtime_version 設定支援 semver。

    • 在應用程式的 package.json 檔案中，使用 engines 欄位加入支援的最新 Node.js 版本。使用 engines 欄位指定版本時，系統會優先採用 runtime_version 設定。為防止意料之外的毀損發生，建議您在 engines 欄位中指定 Node.js 版本，並一併指定 runtime_version。例如：

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

      engines.node 屬性可為 semver 範圍。如果您指定這項屬性，執行階段會下載並安裝符合 semver 範圍的最新版 Node.js。如果找不到相符項目，應用程式將無法部署，且執行階段會傳回錯誤。

先前的執行階段版本

如要使用 16 以上版本的 Node.js 執行階段，請在應用程式的 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 區段中指定其他套件管理員檔案，以解決系統要使用哪一個套件管理員的問題。

套件管理員版本

該執行階段映像檔的目的在於使用 yarn 最新版本，以及 Node.js LTS 最新版本提供的 npm 版本。

您可以在應用程式的 package.json 檔案中，使用 engines 欄位指定要使用的其他套件管理員版本。在這種情況下，執行階段會確保用於部署的套件管理員版本與 engines 欄位所列的規格相符。

如果同時提供 yarn 和 npm 版本規格，只有用於部署的套件管理工具會在需要時更新。如此就不需要安裝自訂版本的套件管理員，進而省下部署時間 (假設該套件管理員實際上不會用來部署您的應用程式)。

以下範例會將執行階段設定為使用自訂版本的 npm：

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

下一個範例會設定執行階段，以使用自訂版本的 yarn：

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

engines.npm 和 engines.yarn 屬性皆可為 semver 範圍。

依附元件

在部署期間，執行階段會執行 npm install 或 yarn install，藉此使用 npm 或 yarn 套件管理員來安裝依附元件。如要進一步瞭解執行階段如何選取要使用的套件管理工具，請參閱「套件管理工具」一節。

此外，如要進一步瞭解在 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 啟動應用程式，而 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 和轉送 Proxy

App Engine 會在負載平衡器上終止 HTTPS 連線，並將要求轉送至您的應用程式。部分應用程式需要判斷原始要求 IP 和通訊協定。使用者的 IP 位址位於標準 X-Forwarded-For 標頭中。需要此項資訊的應用程式需要將網路架構設定為信任該 Proxy。

如要使用 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 位址。

import express from 'express';
import fetch from '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.');
});