環境変数とモード

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

組み込み定数

いくつかの組み込み定数は常に利用可能です。

• 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 オプションを参照してください。

環境変数の解析

上記のように、VITE_SOME_KEY は数値ですが、解析されると文字列として返されます。これはブーリアン型の環境変数でも同様です。コードで使用する際は、必要な型に変換するようにしてください。

.env ファイル

Viteは、dotenv を使用して、環境ディレクトリ内の以下のファイルから追加の環境変数を読み込みます。

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode, ignored by git

環境変数の読み込み優先順位

特定のモード用のenvファイル（例: .env.production）は、汎用的なもの（例: .env）よりも高い優先順位を持ちます。

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

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

.env ファイルはViteの開始時に読み込まれます。変更を加えた後はサーバーを再起動してください。

また、Viteは dotenv-expand を使用して、envファイルに記述された変数をすぐに展開します。構文の詳細については、彼らのドキュメントを確認してください。

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

.env

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

セキュリティに関する注意

• .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 のような他のツールでは機能しません。とはいえ、Viteは dotenv-expand で長い間サポートされており、JavaScriptエコシステムの他のツールもこの動作をサポートする古いバージョンを使用しているため、この動作をサポートしています。

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

TypeScriptのIntelliSense

デフォルトでは、Viteはvite/client.d.tsで import.meta.env の型定義を提供します。.env.[mode] ファイルでさらにカスタムの環境変数を定義できますが、VITE_ プレフィックスを持つユーザー定義の環境変数についてTypeScriptのIntelliSenseを取得したい場合があります。

これを行うには、src ディレクトリに vite-env.d.ts を作成し、ImportMetaEnv を次のように拡張します。

vite-env.d.ts

/// <reference types="vite/client" />

interface ViteTypeOptions {
  // By adding this line, you can make the type of ImportMetaEnv strict
  // to disallow unknown keys.
  // strictImportMetaEnv: unknown
}

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // more env variables...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

コードがDOMやWebWorkerなどのブラウザ環境の型に依存している場合、tsconfig.json の lib フィールドを更新できます。

tsconfig.json

{
  "lib": ["WebWorker"]
}

importがあると型拡張が壊れます

ImportMetaEnv の拡張が機能しない場合は、vite-env.d.ts に import ステートメントがないことを確認してください。詳細については、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%）、それは無視され、置換されません。これは、JavaScriptで import.meta.env.NON_EXISTENT が undefined に置換されるのとは異なります。

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 オプションフラグを渡すことで、コマンドに使用されるデフォルトモードを上書きできます。例えば、ステージングモード用にアプリをビルドしたい場合：

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）とモードは2つの異なる概念であることに注意することが重要です。ここでは、異なるコマンドが 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 ファイルでも設定できます。もし NODE_ENV が .env.[mode] ファイルで指定されている場合、モードはその値を制御するために使用できます。ただし、NODE_ENV とモードは依然として2つの異なる概念として残ります。

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