環境変数とモード

環境変数

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} アプリがサーバーで実行されているかどうか。

.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ファイル (例： .env) よりも優先順位が高くなります。

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

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

.env ファイルは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

環境変数の解析

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

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

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

.env

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

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

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

• .env.*.local ファイルはローカル専用であり、機密性の高い変数を含めることができます。gitにチェックインされないように、*.local を .gitignore に追加する必要があります。

• Viteのソースコードに公開された変数は、クライアントバンドルに含まれるため、`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 ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // more env variables...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

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

tsconfig.json

{
  "lib": ["WebWorker"]
}

インポートは型の拡張を壊します

ImportMetaEnv の拡張が機能しない場合は、vite-env.d.ts に import 文がないことを確認してください。詳細については、TypeScriptのドキュメントを参照してください。

HTMLの環境変数置換

Viteは、HTMLファイル内の環境変数の置換もサポートしています。 import.meta.env のプロパティは、特別な %ENV_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` として置換されるのではなく、無視され置換されません。

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) とモードは異なる概念であることに注意することが重要です。さまざまなコマンドが `NODE_ENV` とモードにどのように影響するかを以下に示します。

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

NODE_ENV=development vite build

コマンド	production	NODE_ENV=development vite build --mode development
development	NODE_ENV とモードの異なる値は、対応する `import.meta.env` プロパティにも反映されます。	import.meta.env.PROD
import.meta.env.DEV	import.meta.env.PROD	NODE_ENV とモードの異なる値は、対応する `import.meta.env` プロパティにも反映されます。
NODE_ENV=production	import.meta.env.PROD	NODE_ENV とモードの異なる値は、対応する `import.meta.env` プロパティにも反映されます。

コマンド	true
false	"production"
NODE_ENV=development	vite build --mode development
false	true

NODE_ENV=other

false

true