「ビルドの呪縛」から解放される：Vite環境変数のランタイム・インジェクション完全攻略
こんにちは。開発環境を極めることに情熱を燃やす、あなたのアーキテクトです。
フロントエンド開発の現場で、「Staging用とProduction用で、わざわざ2回もビルドし直していませんか？」と聞くと、多くのエンジニアが苦笑します。CI/CDパイプラインを回すたびに数分を浪費し、成果物が環境ごとに異なる（バイナリの不一致が起こる）リスクを抱える……これこそが、従来の「ビルド時環境変数埋め込み（`import.meta.env`）」が抱える最大の弱点です。
今日は、「一度ビルドしたコンテナを、設定だけ書き換えてあらゆる環境で使い回す」という、DevOpsの理想を実現するランタイム・インジェクションの極意を伝授します。これをマスターすれば、あなたのデプロイフローは劇的に速く、そして堅牢になります。
—
なぜ「ビルド時の環境変数」ではいけないのか？
Viteなどのビルドツールは、デフォルトで `VITE_` 接頭辞のついた変数をビルド時にコードへハードコーディングします。これは非常に高速ですが、「ビルドした瞬間に設定が固定される」という致命的な性質を持ちます。
これでは、Dockerコンテナを「ビルド済みアーティファクト」としてレジストリに保存し、それを環境（Dev/Staging/Prod）に横展開するという、現代のクラウドネイティブな戦略が取れません。環境ごとにビルドしていると、テストしたバイナリと本番のバイナリが別物になるという「非決定性」の問題が常に付きまといます。
私たちが目指すのは、「ビルドは一度きり。実行時に設定を注入する」というアプローチです。
—
手法：ランタイム・インジェクションの設計思想
仕組みはシンプルです。
1. アプリ実行時に読み込まれる `config.js` を用意する。
2. その中身を、サーバー起動時にシェルスクリプトで差し替える。
3. ブラウザが読み込むタイミングで、その設定をアプリケーションに注入する。
ステップ1：設定ファイルの分離
`public/config.js` というファイルをプロジェクトの公開ディレクトリに作成します。これはビルド処理を通さず、そのままブラウザへ配信されるファイルです。
// public/config.js
// このファイルはビルドされず、そのまま配信されます
window.APP_CONFIG = {
API_BASE_URL: “__API_BASE_URL__”, // ここを後でシェルで書き換えます
DEBUG_MODE: “__DEBUG_MODE__”
};
ステップ2：エントリーポイントでの読み込み
`index.html` の `
` 内で、この設定ファイルを最優先で読み込みます。
これで、アプリケーションコード内からいつでも `window.APP_CONFIG.API_BASE_URL` として環境値にアクセス可能になります。
—
現場で震えるほど役立つ：動的置換シェルスクリプト
Dockerコンテナ起動時に、環境変数をもとに `config.js` を書き換えるためのスクリプト `entrypoint.sh` を用意します。
!/bin/sh
entrypoint.sh
設定ファイルのパス
CONFIG_FILE=”/usr/share/nginx/html/config.js”
環境変数をsedで物理的に置換する
実行環境の環境変数を読み取り、__プレースホルダー__を値で上書きします
sed -i “s|__API_BASE_URL__|$API_BASE_URL|g” $CONFIG_FILE
sed -i “s|__DEBUG_MODE__|$DEBUG_MODE|g” $CONFIG_FILE
Nginxをフォアグラウンドで起動
nginx -g ‘daemon off;’
このスクリプトをDockerの `ENTRYPOINT` に設定しておけば、コンテナ起動時にその環境の `API_BASE_URL` が確実に反映されます。
—
なぜこの手法が最強なのか？
1. Immutable Infrastructure（不変のインフラ）の実現:
一度ビルドしたイメージをStagingとProductionで全く同じものとして扱えます。デプロイの信頼性が飛躍的に向上します。
2. CI時間の劇的短縮:
ビルドはリポジトリの変更時のみ。環境ごとのデプロイはコンテナを起動するだけで完了するため、パイプラインの待ち時間が最小化されます。
3. ブラウザキャッシュの制御:
`config.js` を適切なキャッシュヘッダーで配信すれば、設定変更時に即座に反映させることも容易です。
—
初心者へのアドバイス：まずは「ローカル確認」から
この仕組みを導入する際、まずはDockerなしで手動で確認してみましょう。
1. `npm run build` を実行して `dist/` ディレクトリを作る。
2. `dist/config.js` の中身をテキストエディタで直接書き換える。
3. `npx serve dist` でローカルサーバーを立て、ブラウザの開発者コンソールで `window.APP_CONFIG` を叩いてみる。
「自分で文字列を書き換えただけで、アプリの設定が変わった！」というこの瞬間、あなたは環境変数という「ビルドの壁」を突破したことになります。
—
終わりに
開発環境のアーキテクチャを最適化することは、単なる効率化ではありません。「開発者が、コードのロジックそのものに集中できる環境を整えること」こそが、最高の結果を生むための唯一の道です。
Viteの柔軟性と、このランタイム・インジェクションの戦略を組み合わせれば、どんなに複雑なマルチステージ環境でも恐れることはありません。明日からのあなたのビルドフローが、より軽やかで確実なものになることを願っています。
何か詰まったら、いつでも聞いてください。設計レベルから一緒に考えましょう。