ReactとViteで、.envの環境変数を読み込む方法

​​Vite​React,TypeScript,環境変数

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つのファイルを用意しました。

text
--- .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.名前 で読みます。

ts
// 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 の主な部分です)。

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 の結果です)。

text
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行が足されていました。

text
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/ の中を文字列で探した結果が次です。

text
$ 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 の中身が次のようなオブジェクトとして書き込まれていました。

text
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 で開いたときの画面が次です。

本番ビルドを開いた画面。MODE が production、VITE_ENABLE_DEBUG が文字列の "false"、デバッグ表示はオフだが、文字列のまま条件に使った行はオンになっている
本番ビルドの画面。最後の行だけオンになる

画面の下の2行は、同じ VITE_ENABLE_DEBUG から作った表示です。=== 'true' で比べた「デバッグ表示」はオフですが、env.VITE_ENABLE_DEBUG ? 'オン' : 'オフ' と文字列のまま条件に使った行はオンになりました。"false" は空でない文字列なので、条件の中では真として扱われます。

公式ドキュメントにも、数値や真偽値は文字列として返るので、使う形に直すよう書かれています。直す処理は、上の src/config.ts のように1か所にまとめておくと、コンポーネントの中で比べ方がばらばらになりません。

モードで読み込む .env ファイルを切り替える

Vite が読み込む .env ファイルは、モードによって変わります。開発サーバーのモードは development、vite build のモードは production です。公式ドキュメントにある読み込み先は、次の2つが基本です(コメントは私が日本語にしました)。

text
.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 に書いた値は、ビルドするときのシェルの環境変数で上書きできます。

text
$ 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行が出ました。

text
[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 も最後まで終わりました。

ts
// 綴りを間違えた変数名
export const url: string = import.meta.env.VITE_API_UR

公式ドキュメントの TypeScript の節にあるとおり、src/vite-env.d.ts を作って ImportMetaEnv に自分の値を書き足すと、型が付きます。ただし、名前を書き足すだけでは、上の綴りの間違いはまだ通りました。知らない名前をエラーにするには、ViteTypeOptions に strictImportMetaEnv を足します。

ts
// 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 を実行すると、次のエラーが出ました。

text
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 文を書くと、この書き足しが効かなくなります。

​Posted by 86