環境変数とモード ​

環境変数 ​

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

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

読み込まれた環境変数は、import.meta.env を経由してクライアントソースコードにも文字列として公開されます。

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

VITE_SOME_KEY=123
DB_PASSWORD=foobar

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

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

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

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

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

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

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

TypeScript 用の自動補完 ​

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

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

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

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

interface ImportMeta {
  readonly env: ImportMetaEnv
}

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

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

interface ImportMeta {
  readonly env: ImportMetaEnv
}

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

{
  "lib": ["WebWorker"]
}

{
  "lib": ["WebWorker"]
}

HTML での置換 ​

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

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

<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

# .env.production
VITE_APP_TITLE=My App

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

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

vite build --mode staging

vite build --mode staging

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

# .env.staging
VITE_APP_TITLE=My App (staging)

# .env.staging
VITE_APP_TITLE=My App (staging)

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

# .env.testing
NODE_ENV=development

# .env.testing
NODE_ENV=development

NODE_ENV とモード ​

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

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