Vite で環境変数（import.meta.env）が読み込めない

Vite は VITE_ プレフィックスを付けた変数のみをクライアントへ公開する。.env を置いたのに undefined になる典型例と、サーバー専用変数の扱いを整理する。

#env #import-meta-env #vite-prefix #dotenv #build

公開: 2026-06-02更新: 2026-09-07

実行例あり（2026-09-07 に実環境で検証）

要約

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
終了コード: 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 時点の出力

検証環境

検証日

2026-09-07

実行環境

node:20Debian GNU/Linux 12 (bookworm)

バージョン

Node.js 20.20.2
npm 10.8.2
Python 3.11.2
Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

よくある原因

プレフィックス忘れ: .env に API_URL=... と書いてもクライアントからは読めない。
配置ミス: vite を実行している作業ディレクトリと .env の場所が一致していない（モノレポで起こりやすい）。
再起動忘れ: 環境変数は起動時のスナップショットなので、.env を編集しても HMR では反映されない。
CI で値が無い: ローカルの .env.local は通常 .gitignore に入っているため、CI では未定義になる。
mode 不一致: vite build --mode staging なら .env.staging が読まれる。.env.production を置いていてもロードされない。

解決策

1. プレフィックスを付ける

# .env
VITE_API_URL=https://api.example.com

const 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 dev

4. 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 を読む

要約

実行例