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 位址。