Vite環境変数の深淵：フロントエンドの境界線を越えるアーキテクチャ設計
多くのエンジニアが「`VITE_`を付ければブラウザから見える」という表層的な理解で満足しているが、それは火薬庫の上に座っているのと同じだ。我々アーキテクトにとって、環境変数とは「ビルド時のメタデータ注入」であり、セキュリティと構成管理の要である。
なぜViteは`VITE_`という接頭辞を強制するのか。そして、なぜCI/CDとDocker環境で「ビルド時注入」と「実行時注入」の境界線を曖昧にしてはいけないのか。その真髄を紐解く。
—
1. `import.meta.env` の正体とロード順序の物理層
Viteは起動時、`dotenv`ライブラリを用いて`.env`ファイルを読み込む。しかし、ここには落とし穴がある。Viteは、環境変数をビルドプロセスにおいて「静的な文字列置換」としてコードに焼き付ける。
優先順位の真実
Viteは以下の順序で読み込みを行い、後続のファイルが先行する値を上書きする。
1. `.env` (デフォルト)
2. `.env.local` (Git管理外)
3. `.env.[mode]` (例: `.env.production`)
4. `.env.[mode].local` (Git管理外)
アーキテクトの知見：
なぜ `process.env` ではなく `import.meta.env` なのか。それは `process` オブジェクトがNode.jsのランタイム依存であり、ブラウザ環境ではポリフィルが必要になるからだ。ViteはESMの仕様に準拠し、ビルド時にこれらの変数を `import.meta.env` というオブジェクトに静的にマッピングする。これにより、コードのバンドルサイズを最小化し、不要な環境変数の混入を防いでいるのだ。
—
2. CI/CDパイプラインにおける「ビルド時注入」の罠
多くの現場で、「Dockerコンテナを立ち上げてから環境変数を書き換える」という誤ったアプローチが見られる。Viteはビルドツールであり、実行時に環境変数を読み取るランタイムツールではない。
コンテナ環境で正しい設計を行うなら、以下の「多段ビルド戦略」を徹底すべきだ。
Stage 1: ビルド環境（ここでの環境変数が静的に埋め込まれる）
FROM node:20-alpine AS builder
WORKDIR /app
COPY . .
ビルド時に環境変数を直接渡す（VITE_で始まるもののみ有効）
RUN VITE_API_URL=https://api.production.com npm run build
Stage 2: 配信環境（Nginx等）
FROM nginx:alpine
COPY –from=builder /app/dist /usr/share/nginx/html
注意：この時点で環境変数は既にビルド結果にハードコードされている
現場の教訓：
「コンテナを1つ作成し、環境変数だけ変えてステージングと本番を使い回したい」という要望は、フロントエンド開発においてはアンチパターンだ。もし実行時に動的に変数を変更したいのであれば、それはViteの領域ではなく、`window.__RUNTIME_CONFIG__` のような外部JSONファイルを `public/` に配置し、それをフェッチするランタイム注入アーキテクチャへ移行せよ。
—
3. セキュリティの防壁：`VITE_`接頭辞の存在意義
なぜ接頭辞が必要なのか？ それは、プロジェクトルートに存在する`.env`ファイルには、データベースのパスワードやシークレットキーが混在することがあるからだ。
Viteのアーキテクチャは、誤って `DB_PASSWORD` をコードに含めてしまうリスクを排除するために、あえてホワイトリスト方式を採用している。
防御的エンジニアリングの極意
機密情報を扱う場合、`.env` ファイルには絶対に入れず、CI/CDのシークレットストアからビルドパイプラインへ注入せよ。
GitHub Actionsの例
- name: Build
run: npm run build
env:
# 外部シークレットを一時的な環境変数としてViteに渡す
VITE_STRIPE_PUBLIC_KEY: ${{ secrets.STRIPE_PUBLIC_KEY }}
これを行うことで、Gitリポジトリには決して機密情報が残らず、かつビルド成果物（dist/）には必要な公開キーのみが埋め込まれる。
—
4. 高度な最適化：`define` プロパティの活用
`.env`ファイルに頼り切る必要はない。`vite.config.ts` の `define` オブジェクトを使えば、ビルド時により強力な制御が可能だ。
// vite.config.ts
export default defineConfig({
define: {
// 任意のグローバル定数を注入する
__APP_VERSION__: JSON.stringify(process.env.npm_package_version),
__BUILD_DATE__: JSON.stringify(new Date().toISOString()),
},
})
これにより、コード内で `console.log(__APP_VERSION__)` と書くだけで、ビルド時にバージョン番号が直接展開される。これは環境変数ファイルを管理する手間を省き、CI環境のビルドログから直接情報を引き出せるため、トレーサビリティが飛躍的に向上する。
—
結論：アーキテクトが目指すべき地平
Viteにおける環境変数の管理は、単なる「設定値の読み込み」ではない。それは、「どこまでをコンパイル時に確定させ、どこからをランタイムに委ねるか」という境界線設計そのものだ。
1. ビルド時に確定できるもの（APIエンドポイント、公開キー）は `.env` 経由で静的注入せよ。
2. 機密情報はビルドパイプラインから直接供給し、リポジトリをクリーンに保て。
3. コンテナ配布を前提とするなら、ランタイム注入（JSON読み込み）を検討せよ。
この設計思想を理解したエンジニアこそが、複雑なマイクロフロントエンドの構成においても、強固で予測可能なデプロイパイプラインを構築できる。さあ、今すぐ不要な `.env.local` を削除し、堅牢なパイプラインを設計しよう。