ReactとViteで、.envの環境変数を読み込む方法
Vite で作った React アプリでは、.env ファイルに VITE_ で始まる名前で値を書くと、コードから import.meta.env.VITE_API_URL のように読めます。開発中はローカルの API サーバー、本番は公開用のサーバーというように、開発環境と本番環境で API の接続先や設定を切り替えたいときに使う仕組みです。
私は検証環境で、.env と .env.development に値を書き、開発サーバー・本番ビルド・--mode staging のビルドで、画面に出る値を確かめました。値が文字列になる点と、ビルドした JS ファイルに値がそのまま書き込まれる点も、実際の出力で確かめています。
検証環境は Ubuntu 24.04、Node.js 22.23.4、Vite 8.3.8、@vitejs/plugin-react 6.3.0、React 19.3.1、TypeScript 7.0.2 です。プロジェクトは npm create vite@latest の react-ts テンプレートで作りました。画面の値は Playwright 1.63.0 の Chromium で開いて読み取りました。名前が .local で終わる .env ファイル、envPrefix の変更、Windows・macOS は試していません。
.env に VITE_ で始まる名前で書く
プロジェクトの直下(package.json と同じ場所)に .env を置き、名前=値 の形で書きます。今回は次の3つのファイルを用意しました。
--- .env
VITE_APP_TITLE=猫の手メモ
VITE_API_URL=https://api.example.com
VITE_ENABLE_DEBUG=false
DB_PASSWORD=foobar
--- .env.development
VITE_API_URL=http://localhost:3000
VITE_ENABLE_DEBUG=true
--- .env.staging
VITE_API_URL=https://staging.example.com
コードからは import.meta.env.名前 で読みます。
// src/config.ts
// 文字列で入っているので、使う形に直してから export する
export const apiUrl = import.meta.env.VITE_API_URL
export const debugEnabled = import.meta.env.VITE_ENABLE_DEBUG === 'true'
画面には、import.meta.env の中身を表にして出しました(App.tsx の主な部分です)。
// src/App.tsx(一部)
const env = import.meta.env
const rows: [string, unknown][] = [
['MODE', env.MODE],
['DEV', env.DEV],
['PROD', env.PROD],
['BASE_URL', env.BASE_URL],
['VITE_APP_TITLE', env.VITE_APP_TITLE],
['VITE_API_URL', env.VITE_API_URL],
['VITE_ENABLE_DEBUG', env.VITE_ENABLE_DEBUG],
]
npm run dev で起動する開発サーバーで開くと、表の値は次のとおりでした(左から、名前、値、typeof の結果です)。
MODE | "development" | string
DEV | true | boolean
PROD | false | boolean
BASE_URL | "/" | string
VITE_APP_TITLE | "猫の手メモ" | string
VITE_API_URL | "http://localhost:3000" | string
VITE_ENABLE_DEBUG | "true" | string
VITE_API_URL と VITE_ENABLE_DEBUG は、.env ではなく .env.development の値になっています。VITE_APP_TITLE は .env にしかありませんが、そのまま読めています。
MODE、DEV、PROD、BASE_URL は自分で書いていない値です。Vite の公式ドキュメントの「環境変数とモード」にあるとおり、Vite が最初から用意している値で、MODE はいまのモード、DEV と PROD は開発か本番か、BASE_URL はアプリを配信するパス(base の設定)を表します。
VITE_ が付かない値はブラウザに渡らない
.env に書いた DB_PASSWORD は、import.meta.env に入りませんでした。開発サーバーが配信した変換後の src/config.ts の先頭には、次の1行が足されていました。
import.meta.env = {"BASE_URL": "/", "DEV": true, "MODE": "development", "PROD": false, "SSR": false, "VITE_API_URL": "http://localhost:3000", "VITE_APP_TITLE": "猫の手メモ", "VITE_ENABLE_DEBUG": "true"};
ブラウザ側のコードに渡るのは VITE_ で始まる値と、Vite が用意している値だけです。公式ドキュメントでも、VITE_ が付いた値だけをクライアントのコードに出すのは、うっかり漏らさないためと説明されています。
逆に言えば、VITE_ を付けた値は誰でも見られる場所に出ます。npm run build でビルドしたあと、dist/ の中を文字列で探した結果が次です。
$ grep -o 'https://api.example.com\|localhost:3000\|foobar\|DB_PASSWORD\|猫の手メモ' -r dist | sort | uniq -c
2 dist/assets/index-C30DF45x.js:https://api.example.com
1 dist/assets/index-C30DF45x.js:猫の手メモ
1 dist/index.html:猫の手メモ
https://api.example.com は JS ファイルに文字列としてそのまま入っていました。foobar(DB_PASSWORD の値)は見つかりません。JS ファイルの中には、import.meta.env の中身が次のようなオブジェクトとして書き込まれていました。
e={BASE_URL:`/`,DEV:!1,MODE:`production`,PROD:!0,SSR:!1,VITE_API_URL:`https://api.example.com`,VITE_APP_TITLE:`猫の手メモ`,VITE_ENABLE_DEBUG:`false`}
VITE_ を付けた値は、ビルドした JS ファイルにそのまま書き込まれ、サイトを開いた人なら誰でも読めます。API キーやパスワードのような秘密の値を VITE_ 付きで書かないでください。公式ドキュメントも、秘密の値はバックエンドのサーバーなどで扱うよう勧めています。
値はすべて文字列になる
VITE_ENABLE_DEBUG=false と書いても、読み出した値は真偽値の false ではなく、文字列の "false" です。表の typeof が string になっているのはそのためです。
本番ビルドを vite preview で開いたときの画面が次です。

画面の下の2行は、同じ VITE_ENABLE_DEBUG から作った表示です。=== 'true' で比べた「デバッグ表示」はオフですが、env.VITE_ENABLE_DEBUG ? 'オン' : 'オフ' と文字列のまま条件に使った行はオンになりました。"false" は空でない文字列なので、条件の中では真として扱われます。
公式ドキュメントにも、数値や真偽値は文字列として返るので、使う形に直すよう書かれています。直す処理は、上の src/config.ts のように1か所にまとめておくと、コンポーネントの中で比べ方がばらばらになりません。
モードで読み込む .env ファイルを切り替える
Vite が読み込む .env ファイルは、モードによって変わります。開発サーバーのモードは development、vite build のモードは production です。公式ドキュメントにある読み込み先は、次の2つが基本です(コメントは私が日本語にしました)。
.env # いつも読み込む
.env.[mode] # 指定したモードのときだけ読み込む
どちらにも、名前の最後に .local を付けたファイル(.env.[mode].local など)があり、同じ場面で読み込まれます。
同じ名前の値があるときは、モード用のファイル(.env.production など)の値が .env の値より優先されます。
検証環境で試したところ、開発サーバーでは .env.development の値、npm run build では .env の値になりました(.env.production は置いていません)。npx vite build --mode staging でビルドすると、MODE は "staging"、VITE_API_URL は .env.staging の "https://staging.example.com" になりました。このとき DEV は false、PROD は true のままでした。--mode で変わるのはモードと読み込むファイルで、本番用のビルドであることは変わりません。
.env に書いた値は、ビルドするときのシェルの環境変数で上書きできます。
$ VITE_API_URL=https://override.example.com npx vite build
このビルドを開くと、VITE_API_URL は "https://override.example.com" になりました。公式ドキュメントにも、Vite を実行する時点ですでにある環境変数がいちばん優先され、.env ファイルでは上書きされないとあります。CI でビルドするときに、接続先だけを外から渡す使い方ができます。
公式ドキュメントでは、名前が .local で終わるファイルは Git に入れないファイルとして説明されています。react-ts テンプレートの .gitignore にも *.local が入っているので、各自の環境だけで使う値はこちらに書けます。
開発サーバーの起動中に .env を書き換えたとき
公式ドキュメントには「.env ファイルは Vite の起動時に読み込まれるので、変更したらサーバーを再起動する」とあります。
検証環境で、開発サーバーを起動したまま .env.development の VITE_API_URL を書き換えたところ、サーバーのログに次の2行が出ました。
[vite] .env.development changed, restarting server...
[vite] server restarted.
そのあとページを開き直すと、書き換えた後の値(http://localhost:4000)になっていました。Vite 8.3.8 では、.env.development の書き換えでサーバーが自動で再起動しました。
TypeScript で VITE_ の値に型を付ける
react-ts テンプレートの tsconfig.app.json には "types": ["vite/client"] が入っていて、import.meta.env の型は Vite が用意しています。ただし、この型は知らない名前も any として通します。src/vite-env.d.ts を置いていない状態では、綴りを間違えた次のコードでも npx tsc -b はエラーを出さず、npm run build も最後まで終わりました。
// 綴りを間違えた変数名
export const url: string = import.meta.env.VITE_API_UR
公式ドキュメントの TypeScript の節にあるとおり、src/vite-env.d.ts を作って ImportMetaEnv に自分の値を書き足すと、型が付きます。ただし、名前を書き足すだけでは、上の綴りの間違いはまだ通りました。知らない名前をエラーにするには、ViteTypeOptions に strictImportMetaEnv を足します。
// src/vite-env.d.ts
interface ViteTypeOptions {
strictImportMetaEnv: unknown
}
interface ImportMetaEnv {
readonly VITE_APP_TITLE: string
readonly VITE_API_URL: string
readonly VITE_ENABLE_DEBUG: 'true' | 'false'
}
これで npx tsc -b を実行すると、次のエラーが出ました。
src/typo.ts(2,44): error TS2551: Property 'VITE_API_UR' does not exist on type 'ImportMetaEnv'. Did you mean 'VITE_API_URL'?
テンプレートの package.json では、npm run build は tsc -b && vite build です。この状態で npm run build を実行すると、同じエラーが出て終了コード 1 で終わり、dist/ は作られませんでした。変数名の打ち間違いを、ビルドの時点で見つけられます。
なお、'true' | 'false' のような型は、.env の中身を確かめるものではありません。この型を付けたまま .env を VITE_ENABLE_DEBUG=yes に変えても、npm run build はエラーなく終わり、画面の値は "yes" になりました。また、公式ドキュメントの注意書きにあるとおり、vite-env.d.ts の中に import 文を書くと、この書き足しが効かなくなります。





