Vite での環境変数の使い方
Vite の環境変数について、.env ファイルの配置場所変更やモード追加、TypeScript 対応などを纏めました。
やりたいこと
開発中にバックエンドと接続しないフロントエンドだけ確認するビルドや、テスト向けに E2E テストするビルド、本番用ビルドなど分けられるようにしたかったので、Vite の環境変数を使って実現しようと考えました。それにあたって、.env ファイルの配置場所変更やモード追加、TypeScript 対応等を、調べてまとめてみました。
Vite の環境変数
Vite は環境変数を特別な
import.meta.envオブジェクトに公開します。
Vite は dotenv (GitHub - motdotla/dotenv: Loads environment variables from .env for nodejs projects.) を利用しているので、.env ファイルに独自の環境変数を追加することでプロジェクト内で使用することができます。
Vite は、環境ディレクトリーにある以下のファイルから追加の環境変数を読み込むために dotenv を利用します。
.env # 全ての場合に読み込まれる .env.local # 全ての場合に読み込まれ、gitには無視される .env.[mode] # 指定されたモードでのみ読み込まれる .env.[mode].local # 指定されたモードでのみ読み込まれ、gitには無視される読み込まれた環境変数は、
import.meta.envを経由してクライアントソースコードにも文字列として公開されます。
.env ファイルの場所
上記公式ドキュメントの引用に「環境ディレクトリ」とありますが、こちらは vite.config.js または vite.config.ts で設定でき、デフォルトはプロジェクトルートです。
envDir
型:string
デフォルト:root
.envファイルを読み込むディレクトリー。絶対パス、もしくはプロジェクトルートからの相対パスを指定します。
設定例は以下の通りです。プロジェクトルート直下の env ディレクトリに .env ファイルを配置するよう指定します。
import { defineConfig } from 'vite'
export default defineConfig({
envDir: './env',
});では実際に .env ファイルを準備します。ここでは VITE_KEY という環境変数を用意し、DEFAULT という文字列を割り当てています。
VITE_KEY=DEFAULTスクリプト内で以下のように環境変数を参照することができます。
const key = import.meta.env.VITE_KEY;
console.log(key);また環境変数は HTML 内でも以下のように参照することができます。
<p>%VITE_KEY%</p>ただしこれはあくまで純粋 HTML ファイルの中での話で Vue.js や Svelte 等のコンポーネントの Template 部分では使えません。それぞれのテンプレート構文にそって import.meta.env で環境変数を参照してください。以下は Vue の例です。
<template>
<p>{{ import.meta.env.VITE_KEY }}</p>
</template>ちなみにこれは dotenv の機能ですが、環境変数の文字列の値はダブルクォーテーションで囲むことで途中で改行することも可能です。 例えば pem ファイルの内容等改行が入れたくなるようなものも以下のように設定できます。（秘密鍵を環境変数で持つのはやめてください）
PRIVKEY="-----BEGIN PRIVATE KEY-----
...........
-----BEGIN PRIVATE KEY-----"環境変数に VITE_ というプレフィクスを付けていますが、これは上記の秘密鍵のような認証情報など機密情報がクライアントコード内に公開されることを防ぐために明示的につける必要があります。
環境変数が誤ってクライアントに漏れてしまうことを防ぐために、VITE_ から始まる変数のみが Vite で処理されたコードに公開されます。
環境変数のプレフィクスの変更
上記プレフィクスは変更可能で、こちらも vite.config.js または vite.config.ts で設定可能です。
envPrefix
型:string|string[]
デフォルト:VITE_
試しにプレフィクスを PUBLIC_ に変えてみましょう。
import { defineConfig } from 'vitest/config';
export default defineConfig({
envDir: './env',
envPrefix: 'PUBLIC_' // 追加
});プレフィクスを変更したので .env ファイル内のプレフィクスも変更します。
PUBLIC_KEY=DEFAULTスクリプト内での環境変数参照も変更しましょう。
const key = import.meta.env.PUBLIC_KEY;
console.log(key);モード
では次にモード毎の .env ファイルを使ってみます。
デフォルトで、開発サーバー（dev コマンド）は development モードで動作し、build コマンドは production モードで動作します。
つまり、 vite build の動作中は、もし .env.production があれば、環境変数をそこから読み込むということです。
以下 2 つのファイル .env.development と .env.production を追加します。
PUBLIC_KEY=DEVELOPMENTPUBLIC_KEY=PRODUCTIONスクリプト内での環境変数参照はそのままです。
const key = import.meta.env.PUBLIC_KEY;
console.log(key)ターミナルで npm run dev を実行して開発サーバーを立ち上げ、console.log の出力を見てみましょう。出力される文字列が DEVELOPMENT に変わっています。
さらにターミナルで npm run build を実行後 npm run preview でビルド結果のプレビューサーバーを立ち上げます。console.log の出力を見てみると PRODUCTION に変わっています。
このようにモードによって環境変数の値を使い分けることが可能です。
開発中はバックエンド API の接続先等が本番と異なることがほとんどだと思いますのでこういった機能は便利ですね。
独自モードの追加
モードには独自モードを追加することもできます。
以下、.env.development2 ファイルを追加します。
PUBLIC_KEY=DEVELOPMENT2次に package.json の scripts 内に dev2 というスクリプトを追加します。
{
// 中略
"scripts": {
"dev": "vite dev",
"dev2": "vite dev --mode development2", // 追加
"build": "vite build",
"preview": "vite preview",
// 中略
}
// 中略
}ポイントは vite の mode オプションに development2 と指定しているところです。
-m, --mode <mode>env モードを設定する (string)
設定は以上ですので、ターミナルで npm run dev2 を実行して console.log の出力内容を見てみましょう。DEVELOPMENT2 となっていると思います。
環境変数の TypeScript 型補完
独自に追加した環境変数は TypeScript の型推論が働きません。型推論させるには個別に型定義をする必要があります。
/src/vite-env.d.ts を作成し、以下のように追加した環境変数の型を定義することで、型推論が効くようになります。
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly PUBLIC_KEY: string
// 追加した環境変数分定義する
}
interface ImportMeta {
readonly env: ImportMetaEnv
}あとがき
Vite の環境変数について纏めました。特にモードの使い分けは開発においてかなり便利なのでぜひ活用してみてください。