Vite と .env と mode と NODE_ENV

はじめに

Vite での .env の扱いについてイマイチわからなかった点を調べて整理します。

Vite での .env の扱いについて

通常の .env の管理とは違うようです。
公式ドキュメントとしてはコチラ。
https://ja.vite.dev/guide/env-and-mode

.env ファイルの項目に以下の説明があります。

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

また、以下の説明があります。

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

つまり、 .env や .env.[mode] はコミットされるのでセンシティブな変数 (パスワードやシークレットキーなど) は書かない。
センシティブな変数は .env.local や .env.[mode].local に書く。

.env.local や .env.[mode].local のテンプレートファイルとして .env.local.template や .env.[mode].local.template ファイルをコミットすると良さそうです。
(これは公式では言及されていない)

[mode] とはなにか

これも同じドキュメント内で言及されていますがわかりにくい。
https://ja.vite.dev/guide/env-and-mode#modes

同じような概念で NODE_ENV があります。
どちらも development と production が定義されています。
しかし、モードは NODE_ENV とは別の概念です。

NODE_ENV

NODE_ENV はビルドの挙動を変更します。
NODE_ENV=development を指定すると開発ビルドになり、コードが minify されないためデバッグしやすくなります。
ただし、ファイルサイズが大きくなるためパフォーマンスが悪くなり、コメントなどがソースコードから読み取れるため公開したくない情報が公開されてしまう懸念があります。
一方で NODE_ENV=production を指定すると本番ビルドになり、コードが minify されます。

Vite ではデフォルトでは vite (vite dev, vite serve と同様) コマンドを実行すると development に、 vite build を実行すると production になります。
NODE_ENV=production vite dev のように環境変数で変更することもできます。

コード上では以下のビルトイン定数で参照することができます。

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

モード

Vite におけるモードは環境を指すものです。
development と prodcution が想定されていますが、 staging など任意のモードを指定する事ができるようです。
モードによって参照する環境変数を変えることが可能です。

Vite では NODE_ENV と同様に、デフォルトでは vite コマンドを実行すると development に、 vite build コマンドを実行すると production になります。
vite dev --mode=production のように --mode パラメータで変更することもできます。

コード上では以下のビルトイン定数で参照することができます。

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

結論

• 開発環境向けの開発サーバー実行
  • vite
  • vite --mode=development
  • NODE_ENV=development vite
  • NODE_ENV=development vite --mode=development
• 本番環境向けの開発サーバー実行
  • vite --mode=development
  • NODE_ENV=production vite
  • NODE_ENV=production vite --mode=development
• 開発環境向けの開発ビルド
  • NODE_ENV=development vite build --mode=development
• 本番環境向けの開発ビルド
  • vite build --mode=development
  • NODE_ENV=production vite build --mode=development
• 開発環境向けの本番ビルド
  • NODE_ENV=development vite build
  • NODE_ENV=development vite build --mode=production
• 本番環境向けの本番ビルド
  • vite build
  • vite build --mode=production
  • NODE_ENV=production vite build
  • NODE_ENV=production vite build --mode=production

ややこしいなと思いました。