本頁面由 Cloud Translation API 翻譯而成。

Node.js 執行階段

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

Node.js 版本

Node.js 22 會使用Buildpack。預設的 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 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 以下版本，請使用 engines 欄位，在應用程式的 package.json 檔案中指定版本。

以下範例會將執行階段設定為使用 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 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。如果您需要在啟動應用程式之前進一步控制建構步驟，可以將 gcp-build 指令碼新增至 package.json 檔案，藉此提供自訂建構步驟。

如要避免建構執行 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.');
});