Vite で環境変数(import.meta.env)が読み込めない
Vite は VITE_ プレフィックスを付けた変数のみをクライアントへ公開する。.env を置いたのに undefined になる典型例と、サーバー専用変数の扱いを整理する。
公開: 更新:
症状できない
npx vite build … rendering chunks... computing gzip size... dist/main.js 0.08 kB │ gzip: 0.07 kB ✓ built in 32ms
2026-09-07 に node:20(Node.js 20.20.2 / npm 10.8.2) で実際に打って取った出力。検証環境の詳細
要約
import.meta.env.VITE_FOO が undefined になる場合、原因のほとんどは、VITE_ プレフィックスが付いていない か dev サーバーを再起動していない かのどちらかである。
Vite はセキュリティ上、VITE_ プレフィックス無しの変数を一切クライアントに公開しない。
実行例
VITE_ を付けない API_URL は、ビルド自体は通るのに実行時は undefined のままになる。
接頭辞を付けた変数だけが値として埋め込まれ、loadEnv は第 3 引数に空文字を渡したときだけ接頭辞なしの変数も返している。
$ npx vite build
vite v6.4.3 building for production...
transforming...
✓ 1 modules transformed.
rendering chunks...
computing gzip size...
dist/main.js 0.08 kB │ gzip: 0.07 kB
✓ built in 32ms
$ echo $?
0$ node dist/main.js
API_URL = undefined
VITE_API_URL = undefined$ npx vite build
vite v6.4.3 building for production...
transforming...
✓ 1 modules transformed.
rendering chunks...
computing gzip size...
dist/main.js 0.10 kB │ gzip: 0.10 kB
✓ built in 78ms$ node dist/main.js
API_URL = undefined
VITE_API_URL = https://api.example.com$ node check-loadenv.mjs
loadEnv(mode, cwd) = { API_URL: undefined, VITE_API_URL: 'https://api.example.com' }
loadEnv(mode, cwd, "") = {
API_URL: 'https://api.example.com',
VITE_API_URL: 'https://api.example.com'
}— 2026-09-07 時点の出力
検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-09-07 検証(ほか 1 件)
- 検証日
- 実行環境
node:20Debian GNU/Linux 12 (bookworm)- バージョン
- Node.js 20.20.2
- npm 10.8.2
- Python 3.11.2
- Git 2.39.5
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. プレフィックスを付ける
# .env
VITE_API_URL=https://api.example.comconst url = import.meta.env.VITE_API_URL;ビルド時に置換されるため、シークレットを置いてはならない(公開される)。
2. サーバー側で読む場合は loadEnv
vite.config.ts から .env を読みたい時はプレフィックス無しでも loadEnv で取れる(公式ドキュメント(新しいタブで開く))。
import { defineConfig, loadEnv } from "vite";
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), "");
return {
define: {
__APP_VERSION__: JSON.stringify(env.APP_VERSION),
},
};
});第 3 引数を "" にすると全変数(プレフィックス無し含む)を取得できる。
3. dev サーバーを再起動する
# Ctrl+C で停止
npm run dev4. TypeScript の型補完を追加する
// src/vite-env.d.ts
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_API_URL: string;
}
interface ImportMeta {
readonly env: ImportMetaEnv;
}5. mode と env ファイル名を揃える
vite build --mode staging # → .env.staging を読むよくある原因
- プレフィックスを付け忘れている。
.envにAPI_URL=...と書いても、クライアントからは読めない。 - ファイルの置き場所を誤っている。
viteを実行している作業ディレクトリと.envの場所が一致していない(モノレポで起こりやすい)。 - dev サーバーを再起動していない。
環境変数は起動時のスナップショットなので、.envを編集しても HMR では反映されない。 - CI に値が無い。
ローカルの.env.localは通常.gitignoreに入っているため、CI では未定義になる。 - mode とファイル名が一致していない。
vite build --mode stagingなら.env.stagingが読まれ、.env.productionを置いていてもロードされない。