Node.js ランタイムは、アプリケーションのコードと依存関係をインストールして、フレキシブル環境でそのアプリケーションを実行する役割を果たすソフトウェア スタックです。
Node.js バージョン
Node.js 20 は Buildpack を使用します。デフォルトの Node.js エンジンは最新の LTS リリースを使用します。サポートされている Node.js のバージョンと、それに対応する Ubuntu のバージョンの完全なリストについては、ランタイム サポート スケジュールをご覧ください。
サポートされている Node.js バージョンを使用するには、次の操作を行う必要があります。
gcloud CLI
バージョン 420.0.0 以降をインストールします。CLI ツールを更新するには、gcloud components update
コマンドを実行します。インストールされているバージョンを表示するには、gcloud version
コマンドを実行します。app.yaml
ファイルにruntime_config
とoperating_system
の設定を追加して、オペレーティング システムを指定します。必要に応じて、次の方法でバージョンを指定します。
app.yaml
ファイルにruntime_version
設定を追加します。runtime_version
の設定が指定されていない場合は、デフォルトで最新の Node.js バージョンが使用されます。次に例を示します。Ubuntu 22 で Node.js 20 を指定するには、次のようにします。
runtime: nodejs env: flex runtime_config: operating_system: "ubuntu22" runtime_version: "20"
Ubuntu 22 でサポートされている最新の Node.js バージョンを指定するには、次のようにします。
runtime: nodejs env: flex runtime_config: operating_system: "ubuntu22"
アプリケーションの
package.json
ファイルで、engines
フィールドを使用して、サポートされている最新の Node.js バージョンを指定する。engines
フィールドを使用してバージョンを指定する場合、runtime_version
の設定が優先されます。予期しない破損を回避するために、engines
フィールドに Node.js のバージョンを指定することをおすすめします。次に例を示します。{ "engines": { "node": "20.x" } }
engines.node
プロパティには semver 範囲を指定できます。このプロパティを指定すると、ランタイムによって、semver 範囲に一致する最新バージョンの 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
セクションにある他のパッケージ マネージャーを指定して、使用するパッケージ マネージャーを決定する必要があります。
パッケージ マネージャー バージョン
ランタイム イメージでは、最新の yarn
リリースと、最新の Node.js LTS リリースで利用可能な 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 パッケージを使用できるように、次の Ubuntu パッケージが Docker イメージにプリインストールされています。
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
を使用してアプリケーションを起動します。その際、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。この ID は、Google Cloud Console に表示されます。 |
NODE_ENV |
アプリがデプロイされている場合、値は production です。 |
PORT |
HTTP リクエストを受信するポート。8080 に設定します。 |
app.yaml
で、追加の構成変数を設定できます。
メタデータ サーバー
アプリケーションのインスタンスは、ホスト名、外部 IP アドレス、インスタンス ID、カスタム メタデータ、サービス アカウント情報など、インスタンスに関する情報を Compute Engine メタデータ サーバーからを取得します。App Engine では、インスタンスごとにカスタム メタデータを設定することはできませんが、プロジェクト単位のカスタム メタデータを設定して、App Engine インスタンスや Compute Engine インスタンスから読み取ることができます。
次のサンプル関数では、メタデータ サーバーからインスタンスの外部 IP アドレスを取得します。