Node.js ランタイム環境

Node.js ランタイムは、ウェブサービスのコードとその依存関係をインストールしてサービスを実行する役割を果たすソフトウェア スタックです。

スタンダード環境の App Engine 用 Node.js ランタイムは、app.yaml ファイル内で次のように宣言されています。

runtime: nodejsVERSION

ここで、VERSION は Node.js の MAJOR バージョン番号です。たとえば、最新の Node.js バージョン(Node.js 20)を使用するには、20 を指定します。

サポートされているその他の Node.js バージョンと、Node.js バージョンに対応する Ubuntu バージョンについては、ランタイム サポート スケジュールをご覧ください。

Node.js バージョン

Node.js ランタイムは、app.yaml ファイルで指定されているバージョンの最新の安定版を使用します。App Engine では、新しいパッチ バージョンとマイナー リリース バージョンへの更新は自動的に行われますが、メジャー バージョンの更新は自動的には行われません。

たとえば、アプリケーションを Node.js 10.9.4 にデプロイすると、その後バージョン 10.10.0 に自動的に更新されますが、Node.js 12.x.x に自動的に更新されることはありません。

マイナー バージョンとパッチ バージョンは自動的に更新されるため、package.json ファイル内のengines.node プロパティではメジャー バージョンのみを指定でき、app.yaml ファイルで指定された Node.js のバージョンと互換性を持ちます。

20 の例:

  • 20.x.x
  • ^20.0.0
  • ~20
  • >=6

package.json ファイル内で互換性のない Node.js バージョンを指定すると、デプロイが失敗し、エラー メッセージが表示されます。

依存関係

デプロイ中に、ランタイムは npm install コマンドを使用して依存関係をインストールします。また、ランタイムは Yarn(yarn.lock)と Pnpm(pnpm-lock.yaml)パッケージ管理システムもサポートしています。詳細については、依存関係の指定をご覧ください。このランタイムによるインストールは新規インストールであるため、node_modules フォルダをアップロードする必要はありません。

このランタイムには、ネイティブ拡張を必要とする Node.js パッケージをサポートするために、ImageMagickFFmpegChrome ヘッドレスなどのツールを使用可能にするシステム パッケージが組み込まれています。パッケージの一覧は、組み込みシステム パッケージをご覧ください。サポートが必要なパッケージがある場合は、Issue Tracker に問題を登録してください。

NPM ビルド スクリプト

デフォルトでは、package.jsonbuild スクリプトが検出されると、Node.js ランタイムによって npm run build が実行されます。アプリケーションの起動前にビルドステップをさらに制御する必要がある場合は、gcp-build スクリプトを package.json ファイルに追加して、カスタム ビルドステップを指定できます。

ビルドで npm run build スクリプトが実行されないようにするには、以下のいずれかを行う必要があります。

  • package.json ファイルに空の値を持つ gcp-build スクリプトを追加します: "gcp-build":""package.json の構成の詳細については、Node.js Buildpack の構成をご覧ください。
  • app.yaml ファイルに空の値を持つ GOOGLE_NODE_RUN_SCRIPTS ビルド環境変数を追加します。

    build_env_variables:
      GOOGLE_NODE_RUN_SCRIPTS: ''
    
ビルド環境変数の指定の詳細については、app.yaml ファイルの build_env_variables セクションをご覧ください。

アプリケーションの起動

デフォルトでは、ランタイムは node server.js を実行してアプリケーションを起動します。package.json ファイルで start スクリプトを指定すると、ランタイムは代わりに指定された起動スクリプトを実行します。次に例を示します。

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

アプリで HTTP リクエストを受信するには、ホスト 0.0.0.0 と、PORT 環境変数で指定され、Node.js で process.env.PORT としてアクセスできるポートでリッスンするウェブサーバーを、start スクリプトで起動する必要があります。

アプリケーションの新しいインスタンスが作成されるたびにスクリプトが実行されるため、パフォーマンスの観点から start スクリプトは軽量にし、ビルドステップを除外する必要があります。

この動作は、app.yamlentrypoint フィールドでスクリプトを指定することによってオーバーライドできます。ランタイムは、node server.js または起動スクリプトを実行する代わりに、entrypoint で指定したコマンドを使用してアプリケーションを起動します。

環境変数

ランタイムは以下の環境変数を設定します。

環境変数 説明
GAE_APPLICATION App Engine アプリケーションの ID。この ID の先頭には「region code~」が付きます。たとえば、ヨーロッパでデプロイされたアプリケーションの場合は「e~」となります。
GAE_DEPLOYMENT_ID 現在のデプロイの ID。
GAE_ENV App Engine の環境。standard に設定します。
GAE_INSTANCE 現在サービスが実行されているインスタンスの ID。
GAE_MEMORY_MB アプリケーション プロセスで使用可能なメモリ量(MB)。
GAE_RUNTIME app.yaml ファイル内で指定したランタイム。
GAE_SERVICE app.yaml ファイル内で指定したサービス名。サービス名が指定されていない場合は、default に設定されます。
GAE_VERSION サービスの現在のバージョン ラベル。
GOOGLE_CLOUD_PROJECT アプリケーションに関連付けられた Google Cloud プロジェクト ID。
PORT HTTP リクエストを受信するポート。
NODE_ENV(Node.js ランタイムでのみ使用可能) サービスがデプロイされたとき production に設定。

app.yaml ファイル内で追加の環境変数を定義できますが、上記の値は NODE_ENV を除きオーバーライドできません。

HTTPS プロキシと転送プロキシ

App Engine は、ロードバランサにおいて HTTPS 接続を終了し、リクエストをアプリケーションに転送します。アプリケーションによっては、元のリクエストの IP とプロトコルが何か確認する必要があります。ユーザーの IP アドレスは、標準の X-Forwarded-For ヘッダーで確認できます。この情報が必要なアプリケーションでは、プロキシを信頼するようにウェブ フレームワークを構成してください。

Express.js では、次の trust proxy 設定を使用します。

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

ファイルシステム

このランタイムには完全なファイル システムが含まれています。このファイル システムの /tmp(App Engine インスタンスの RAM 内のデータを格納する仮想ディスク)以外の場所は読み取り専用です。

メタデータ サーバー

アプリケーションの各インスタンスは、App Engine メタデータ サーバーを使用してインスタンスとプロジェクトに関する情報を照会できます。

次のエンドポイントを介してメタデータ サーバーにアクセスできます。

  • http://metadata
  • http://metadata.google.internal

メタデータ サーバーに送信されるリクエストには、リクエスト ヘッダー Metadata-Flavor: Google を挿入する必要があります。このヘッダーは、メタデータ値を取得する目的でリクエストが送信されたことを示します。

次の表に、特定のメタデータを取得するための HTTP リクエストの各エンドポイントを示します。

メタデータ エンドポイント 説明
/computeMetadata/v1/project/numeric-project-id プロジェクトに割り当てられているプロジェクト番号。
/computeMetadata/v1/project/project-id プロジェクトに割り当てられているプロジェクト ID。
/computeMetadata/v1/instance/region インスタンスが実行されているリージョン。
/computeMetadata/v1/instance/service-accounts/default/aliases
/computeMetadata/v1/instance/service-accounts/default/email プロジェクトに割り当てられているデフォルトのサービス アカウントのメール。
/computeMetadata/v1/instance/service-accounts/default/ プロジェクトのすべてのデフォルトのサービス アカウントを一覧表示します。
/computeMetadata/v1/instance/service-accounts/default/scopes デフォルトのサービス アカウントでサポートされているすべてのスコープを一覧表示します。
/computeMetadata/v1/instance/service-accounts/default/token アプリケーションを他の Google Cloud APIs に認証させるための認証トークンを返します。

たとえば、プロジェクト ID を取得するには、リクエストを http://metadata.google.internal/computeMetadata/v1/project/project-id に送信します。