環境変数とモード

Vite は特定の定数を特別な import.meta.env オブジェクトの下で公開します。この定数は開発中はグローバル変数として定義され、ビルド時にはツリーシェイキングを効果的に行うために静的に置き換えられます。

例

if (import.meta.env.DEV) {
  // この中のコードは本番ビルドでツリーシェイキングされます
  console.log('Dev mode')
}

ビルトイン定数

いくつかのビルトイン定数は全てのケースで利用可能です:

• import.meta.env.MODE: {string} アプリが動作しているモード。

• import.meta.env.BASE_URL: {string} アプリが配信されているベース URL。これは base 設定オプション によって決まります。

• import.meta.env.PROD: {boolean} アプリがプロダクションで動作しているかどうか（NODE_ENV='production' で開発サーバーを起動するか NODE_ENV='production' でビルドしたアプリを実行する）。

• import.meta.env.DEV: {boolean} アプリが開発で動作しているかどうか（常に import.meta.env.PROD の逆）

• import.meta.env.SSR: {boolean} アプリがサーバーで動作しているかどうか

環境変数

Vite は環境変数を import.meta.env オブジェクトの下で自動的に文字列として公開します。

環境変数が誤ってクライアントに漏れてしまうことを防ぐために、VITE_ から始まる変数のみが Vite で処理されたコードに公開されます。例えば、以下の環境変数だと:

.env

VITE_SOME_KEY=123
DB_PASSWORD=foobar

VITE_SOME_KEY だけが import.meta.env.VITE_SOME_KEY としてクライアントソースコードに公開され、DB_PASSWORD は公開されません。

console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined

環境変数のプレフィックスをカスタマイズしたい場合は、envPrefix オプションを参照してください。

env のパース

上に示したように、VITE_SOME_KEY は数値ですが、パースすると文字列が返ります。同じことはブール型の環境変数にも起こります。コード内で使用する場合には、必ず目的の型に変換するようにしてください。

.env ファイル

Vite は、環境ディレクトリーにある以下のファイルから追加の環境変数を読み込むために dotenv を利用します。

.env                # 全ての場合に読み込まれる
.env.local          # 全ての場合に読み込まれ、git には無視される
.env.[mode]         # 指定されたモードでのみ読み込まれる
.env.[mode].local   # 指定されたモードでのみ読み込まれ、git には無視される

env 読み込みの優先度

特定のモードの env ファイル（例: .env.production）は、汎用の env ファイル（例: .env）よりも優先されます。

Vite は特定のモードの .env.[mode] ファイルに加えて、常に .env と .env.local を読み込みます。特定のモードのファイルで宣言された変数は汎用のファイル内の変数より優先されますが、.env または .env.local でのみ定義された変数は、引き続き環境で利用できます。

また、Vite の実行時に既に存在している環境変数は最も優先度が高く、.env ファイルによって上書きされることはありません。例えば、VITE_SOME_KEY=123 vite build を実行する場合。

.env は Vite 起動時に読み込まれます。変更した後はサーバーを再起動してください。

Bun ユーザー

Bun を使用する際、Bun はスクリプトの実行前に .env ファイルを自動的に読み込むことに注意してください。この組み込み動作により、環境変数が直接 process.env に読み込まれ、既存の process.env の値を尊重する Vite の機能に干渉する可能性があります。回避策については oven-sh/bun#5515 を参照してください。

また、Vite は dotenv-expand を使って、設定不要で env ファイルに書かれた変数を展開できます。構文の詳細については、ドキュメントを参照してください。

環境値の中で $ を使用する場合は、\ でエスケープする必要があることに注意してください。

.env

KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123

SECURITY NOTES

• .env.*.local ファイルはローカル限定で、センシティブな変数を含めることができます。git にチェックインされるのを防ぐために、.gitignore に *.local を追加すべきです。

• Vite のソースコードに公開される変数は最終的にクライアントバンドルに入るので、VITE_* 変数はセンシティブな情報を含まないようにすべきです。

変数の逆順展開

Vite は変数を逆順で展開することをサポートしています。 たとえば、以下の .env は VITE_FOO=foobar、VITE_BAR=bar として評価されます。

.env

VITE_FOO=foo${VITE_BAR}
VITE_BAR=bar

これはシェルスクリプトや docker compose のような他のツールでは動作しません。 とはいえ、この挙動は dotenv-expand によって長い間サポートされてきたものであり、JavaScript エコシステム内の他のツールでは、この挙動をサポートする古いバージョンが使用されているため、Vite はこの挙動をサポートしています。

相互運用性の問題を回避するため、この挙動に依存しないことをお勧めします。Vite は将来的にこの挙動に対して警告を発するようになる可能性があります。

TypeScript 用の自動補完

デフォルトで Vite は vite/client.d.ts で import.meta.env のための型定義を提供します。.env.[mode] ファイルで自前の環境変数を定義できますが、VITE_ で始まるユーザー定義の環境変数に対する TypeScript の自動補完が欲しくなるかもしれません。

この目的を達するには、src ディレクトリーに vite-env.d.ts を作成し、以下のように ImportMetaEnv を補ってください:

vite-env.d.ts

interface ViteTypeOptions {
  // この行を追加することで ImportMetaEnv の型を厳密にし、不明なキーを許可しないように
  // できます。
  // strictImportMetaEnv: unknown
}

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // その他の環境変数...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

コードがブラウザー環境の型、例えば DOM や WebWorker に依存している場合は、tsconfig.json 内の lib フィールドを更新しましょう。

tsconfig.json

{
  "lib": ["WebWorker"]
}

import は型拡張を破壊する

ImportMetaEnv の拡張が上手く動かない場合、import ステートメントが vite-env.d.ts 内に存在しないことを確認してください。詳しい情報については、TypeScript のドキュメント を参照してください。

HTML での定数の置換

Vite は HTML ファイルでの定数の置換もサポートしています。import.meta.env にあるプロパティは、特別な %CONST_NAME% 構文を使用して HTML ファイルで使用できます:

<h1>Vite is running in %MODE%</h1>
<p>Using data from %VITE_API_URL%</p>

環境変数が import.meta.env に存在しない場合（例: %NON_EXISTENT%）、JS では import.meta.env.NON_EXISTENT が undefined として置換されるのとは異なり、（HTML では）無視されて置換されません。

Vite は多くのフレームワークで使用されているため、条件分岐のような複雑な置換については意図的に主張を持たないようにしています。Vite は既存のユーザーランドプラグイン、または transformIndexHtml フックを実装したカスタムプラグインを使って拡張できます。

モード

デフォルトで、開発サーバー（dev コマンド）は development モードで動作し、build コマンドは production モードで動作します。

つまり、 vite build の動作中は、もし .env.production があれば、環境変数をそこから読み込むということです:

.env.production

VITE_APP_TITLE=My App

アプリケーションの中で、import.meta.env.VITE_APP_TITLE を利用してタイトルを描画できます。

場合によっては、vite build を別のモードで実行して、別のタイトルをレンダリングしたいかもしれません。オプションフラグの --mode を渡すことで、コマンドで使用されるデフォルトのモードを上書きすることができます。例えば、staging モード用にアプリをビルドしたい場合:

vite build --mode staging

また、.env.staging ファイルを作成します:

.env.staging

VITE_APP_TITLE=My App (staging)

vite build はデフォルトで本番環境のビルドを実行しますが、別のモードと .env ファイルの設定を変更することで、開発環境のビルドを実行することもできます:

.env.testing

NODE_ENV=development

NODE_ENV とモード

NODE_ENV（process.env.NODE_ENV）とモードは異なる概念であると意識するのが重要です。それぞれのコマンドが NODE_ENV とモードにどのように影響するかを以下に示します:

コマンド	NODE_ENV	モード
vite build	"production"	"production"
vite build --mode development	"production"	"development"
NODE_ENV=development vite build	"development"	"production"
NODE_ENV=development vite build --mode development	"development"	"development"

NODE_ENV およびモードのいろいろな値は、それに対応する import.meta.env プロパティにも反映されます:

コマンド	import.meta.env.PROD	import.meta.env.DEV
NODE_ENV=production	true	false
NODE_ENV=development	false	true
NODE_ENV=other	false	true

コマンド	import.meta.env.MODE
--mode production	"production"
--mode development	"development"
--mode staging	"staging"

.env ファイル内での NODE_ENV

NODE_ENV=... はコマンドや .env ファイルで設定できます。.env.[mode] ファイルで NODE_ENV が指定されている場合、モードを使用してその値を制御できます。ただし、NODE_ENV とモードは依然として異なる概念として残ります。

コマンドでの NODE_ENV=... の主な利点は、Vite がその値を早期に検出できることです。Vite は設定ファイルが評価された後でしか env ファイルを読み込めないので、（コマンドで NODE_ENV を指定すると）Vite の設定内で process.env.NODE_ENV を読み取ることができます。