Vue 3 + Vite で .env が反映されないときのチェックリスト【決定版】

Vue 3 と Vite の組み合わせは開発速度が速く非常に便利ですが、環境変数（.env）の扱いでは思わぬ落とし穴が多数あります。よくあるのは「.env に書いた値が import.meta.env に出てこない」「ビルド後に違う値が埋め込まれる」「ローカルでは動くがデプロイ先で動かない」といった症状です。
本稿は現場で繰り返し発生するトラブルを整理し、原因の見つけ方と対処手順を具体例付きでまとめた 1 本のチェックリストです。順に確認すれば短時間で原因を特定できます。

最初に押さえるべき基本ルール
プレフィックス問題（最頻出）
.env の配置とモード
サーバー再起動とキャッシュの影響
import.meta.env を確実に確認する
TypeScript 特有の問題（型定義）
process.env と import.meta.env の混同
純粋な JS ファイルやビルド対象外ファイル
デプロイ環境での取り扱い（Netlify / Vercel / Cloudflare / Pages）
Docker やコンテナ環境での注意点
追加トラブルシューティング
最後に：確認フロー（実践用）
まとめ

最初に押さえるべき基本ルール

知っておくべき要点

Vite のクライアント向け環境変数は VITE_ プレフィックスが必須。
Vite は起動（ビルド）時に .env を読み込むため、変更後は再起動が必要。
Vite はビルド時に環境変数を埋め込む（ランタイムで Node の process.env を参照する方式ではない）。
これらの基本をまず理解しておくと多くの誤解を防げます。

プレフィックス問題（最頻出）

何が起きるか

.env に API_URL=https://... と書いてもブラウザ側では undefined になります。Vite はセキュリティ目的でクライアントに渡す変数を制限しており、VITE_ で始まるものだけを公開します。

対処方法

クライアントで使う変数は必ず VITE_ を付ける（例：VITE_API_URL）。
サーバー専用の秘密情報は .env に置き、クライアントに渡す必要がある場合のみ VITE_ 付きで設定する。
コンポーネントでは import.meta.env.VITE_API_URL を参照する。

チェックポイント

.env 内のキーに VITE_ が付いているか
ファイル内のスペルミス（例：VITE_API_UR）がないか

.env の配置とモード

配置ミスで読まれないケース

.env を src/ や config/ に置くと Vite は読みません。必ずプロジェクトのルートに配置してください。

mode による読み込みの違い

npm run dev（開発）→ .env ＋ .env.development を読み込み
vite build（本番ビルド）→ .env ＋ .env.production を読み込み
vite build --mode staging → .env ＋ .env.staging を読み込み

対処方法

使用中の mode を確認する（import.meta.env.MODE をログ出力）
CI のビルドコマンドで --mode が指定されていないか確認する

サーバー再起動とキャッシュの影響

なぜ再起動が必要か

Vite は .env をプロセス起動時に評価して一度取り込むため、実行中に .env を編集しても自動で反映されません。新しい変数追加時は必ず dev サーバーの再起動を行ってください。

キャッシュの影響

まれに Vite 側のキャッシュ (node_modules/.vite) が古い状態を保持していて、値が反映されないことがあります。問題が解消しない場合はキャッシュの削除と再インストールを試してください。

rm -rf node_modules/.vite
npm run dev
# 必要なら
rm -rf node_modules
npm install

import.meta.env を確実に確認する

ログで真偽を確かめる

次のように実際に何が読み込まれているかを確認します。

console.log(import.meta.env); // どのキーが存在するか一目瞭然
console.log(import.meta.env.VITE_API_URL);

ここに期待するキーがなければ、Vite が認識していません。まずは .env 名・場所・プレフィックスを再確認してください。

TypeScript 特有の問題（型定義）

型エラーや補完が出ない

TypeScript 環境では import.meta.env の型定義がないと、補完が効かなかったりコンパイルが通らなかったりします。env.d.ts へ型定義を置くか、/// <reference types="vite/client" /> を追加してください。

/// <reference types="vite/client" />
interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  // その他のキー定義
}

チェックポイント

tsconfig.json の typeRoots や include で env.d.ts が除外されていないか確認する

process.env と import.meta.env の混同

よくある間違い

Node.js の慣習で process.env.VITE_API_URL を参照してしまうケースがありますが、Vite のクライアントコードでは必ず import.meta.env を使ってください。process.env はビルド時に一部の bundler が置き換えない限り期待通り動作しません。

純粋な JS ファイルやビルド対象外ファイル

どのファイルが Vite によって処理されるか

import.meta.env は ESM を前提に Vite が処理するファイル内でのみ正しく評価されます。プロジェクトルート直下に置いたスクリプトや CommonJS モジュールでは利用できないことがあります。

対策

該当ファイルを src/ に移動して ESM として扱う
type: module を利用する等、ビルドのターゲットを確認する

デプロイ環境での取り扱い（Netlify / Vercel / Cloudflare / Pages）

デプロイ先での注意点

多くのホスティングは .env.production を自動で読み込まないため、管理画面から環境変数を登録する必要があります。VITE_ を含めたキー名で登録してください。

具体的なチェック

GitHub Actions や CI で env を渡しているか（secrets の設定）
Cloudflare Pages は build 時に環境変数を注入するため、Pages の環境設定にキーがあるか確認する

Docker やコンテナ環境での注意点

マルチステージビルド時のハマりどころ

ビルドコンテナ内で .env を読み込ませる場合、ホストの .env をコンテナに渡しているか、あるいは Dockerfile で環境変数を ARG / ENV に適切に設定しているかを確認します。ビルド時に埋め込む必要がある場合は --build-arg で渡すなどの対応が必要です。

追加トラブルシューティング

空白や全角文字の混入

コピペで末尾にスペースや全角文字が混入し、期待通りマッチしないことがあります。値の前後に不要な空白がないか確認してください。

ハイフンや記号の使用

環境変数名にハイフン（-）やピリオド（.）を使うと参照が不安定になることがあります。VITE_API_URL のようにスネークケースを推奨します。

ファイルのエンコーディング

.env が UTF-8 BOM 付きで保存されていると先頭に不可視文字が混入し、認識されないことがあります。UTF-8（BOM なし）で保存してください。

最後に：確認フロー（実践用）

.env がプロジェクトルートにあるか確認
すべてのクライアント向けキーが VITE_ から始まっているか確認
import.meta.env をコンソールに出して、読み込まれているキーを確認
dev サーバーを再起動しても反映しないか確認（キャッシュ削除を検討）
TypeScript の型定義ファイルが正しく読み込まれているかチェック
デプロイ先（Cloudflare / Netlify / Vercel 等）で同じキーが登録されているか確認
Docker を使う場合はビルド時に環境変数が渡される仕組みになっているか確認

ワンポイントアドバイス

デバッグ時は VITE_DEBUG=true のような一時的フラグを置き、console.log(import.meta.env) を出して変数の有無を確実に把握するのが早道です。

まとめ

Vite の環境変数は単純そうに見えて実は仕様に沿った取り扱いが必要です。
本記事のチェックリストは実務でよく遭遇する原因を網羅しており、順に確認するだけでほとんどのトラブルは解決できます。必要に応じて英語版や図解フローも作成できますので、継続的にチーム内で共有して環境変数の扱いを統一してください。