Vite環境変数ファイルの読み込まれ方について

■はじめに

Viteを使って「ローカル」「dev」「本番」の３つの環境変数を使い分ける方法について、調べて見たので備忘録として残します。

■環境

• "vite": "^7.2.4”
• "react": "^19.2.0"

■Viteプロジェクトのセットアップ

◆プロジェクト作成

# Viteプロジェクトを作成
npm create vite@latest vite-real-estate -- --template react-ts

# プロジェクトに移動
cd vite-real-estate

# 依存関係をインストール
npm install

# 初回起動
npm run dev

プロジェクトをセットアップします。

vite.config.tsですべてのViteの設定を管理します。

Viteでは、index.htmlがルートにあります。

CreateReactAppで作成した場合は、違う場所にルートのindex.htmlファイルがあります。

■環境変数による環境分離

◆なぜ環境を分離するの？

よくある混乱として、npm run devで起動したけど、どのAPIに繋がってる？

ローカル？dev環境？かわからなくなることです。

また、APIの向き先は「local（ローカル環境）」「dev（staging環境）」「prod（本番環境）」で違います。

そこで、envファイルを分けて、コマンド名で明確にわかるようにします。

例えば、以下のような感じです。

• npm run dev → local-devモード → localhost:8000（localのAPIを叩く）
• npm run dev:remote → developmentモード → dev-api.example.com（devのAPIを叩く）
• npm run build → productionモード → api.example.com（本番のAPIを叩く）

今回は、以下のようなenvファイルの構成にします。

vite-real-estate/
├── .env                    # 全環境共通
├── .env.development        # ローカル開発専用
├── .env.staging            # dev(staging)環境専用
├── .env.production         # 本番環境専用
└── .gitignore

◆環境変数ファイルを作成

.envファイルは、全環境で共通で読み込まれます。

そこで、アプリ名やバージョンなど環境に依存しない環境変数を定義します。

# .env(全環境で共通の設定）
VITE_APP_NAME=〇〇アプリ
VITE_VERSION=1.0.0

.env.developmentはローカル開発専用で使う環境変数を定義します。

# .env.development（ローカル開発専用）
VITE_API_URL=http://localhost:8000
VITE_ENV_NAME=ローカル環境
VITE_DEBUG=true

staging環境のAPIなどを環境変数として持つ.env.stagingファイルを作成します。

staging環境は「本番に近い環境でテストできる場所」で「デプロイ前の最終確認」を行います。

# .env.staging（dev・staging環境）
VITE_API_URL=https://dev-api.example.com
VITE_ENV_NAME=開発環境
VITE_DEBUG=true

.env.productionは、実際のユーザーが使うAPI定義などをするファイルです。

DEBUG=falseにすることで、内部情報を表示しないや、不要なログを出さない設定をします。

# .env.production（本番環境用）
VITE_API_URL=https://api.example.com
VITE_ENV_NAME=本番環境
VITE_DEBUG=false

◆package.jsonのスクリプト設定

ローカル、dev、本番で環境を分けるためのscriptsをpackage.jsonに追加します。

各コマンドの意味は、以下になります。

• dev系：HMR有効、ソースコードをそのまま実行
• build系：ビルド・バンドル・圧縮・最適化してdistディレクトリ配下に出力
• preview系：build後のdistフォルダを静的サーバーで確認

コマンド	モード	読み込む環境変数ファイル	用途
npm run dev	development	.env + .env.development	ローカル開発サーバー
npm run dev:staging	staging	.env + .env.staging	staging環境変数で開発サーバー
npm run build	production	.env + .env.production	本番用ビルド
npm run build:staging	staging	.env + .env.staging	staging用ビルド
npm run preview	production	.env + .env.production or env.staging	ビルド結果をローカルでプレビュー
npm run previewを実行する前に、npm run buildを実行するか、npm run build:stagingを実行するかで変わる。

{
  "name": "vite-real-estate",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
		"dev": "vite",
		"dev:staging": "vite --mode staging",
		"build": "vite build",
		"build:staging": "vite build --mode staging",
		"preview": "vite preview",
	},
}

機密情報を守るためにenvファイルは.gitignoreに追加した方がいいです。

代わりに.env.staging.exampleや、.env.production.exampleなどテンプレートファイルを作成して、これをgit管理する方が良いです。
テンプレートファイルには、VITE_API_URL=など変数名だけ記載して、中身は書かないように注意が必要です。

本番の機密情報はCI/CD（Vercel, Netlify, SecretManager等）の環境変数設定で管理するのがより安全だと思います。

ファイル	内容	gitignore
.env	公開可能な共通設定	しない
.env.development	ローカルAPIパスのみ	しなくてもOK
.env.staging	stagingのAPIキー等	する
.env.production	本番のAPIキー等	する

■環境情報を表示するコンポーネントを作成と、動作確認

環境情報ごとの表示するためのコンポーネントを作成します。

• src/App.tsx

  import './App.css';
  
  function App() {
  	// 環境変数を取得
  	const env = import.meta.env;
  	const apiUrl = env.VITE_API_URL;
  	const envName = env.VITE_ENV_NAME;
  	const appName = env.VITE_APP_NAME;
  	const version = env.VITE_VERSION;
  	const showDebug = env.VITE_DEBUG === 'true';
  
  	return (
  		<div
  			style={{
  				padding: '20px',
  				maxWidth: '1200px',
  				margin: '0 auto',
  				fontFamily: 'system-ui, -apple-system, sans-serif',
  			}}
  		>
  			{/* ヘッダー */}
  			<div
  				style={{
  					background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
  					color: 'white',
  					padding: '30px',
  					borderRadius: '10px',
  					marginBottom: '30px',
  					boxShadow: '0 4px 6px rgba(0,0,0,0.1)',
  				}}
  			>
  				<h1 style={{ margin: '0 0 10px 0' }}>{appName}</h1>
  				<h2 style={{ margin: 0, fontWeight: 'normal', opacity: 0.9 }}>
  					{envName} (v{version})
  				</h2>
  			</div>
  
  			{/* デバッグ情報 */}
  			{showDebug && (
  				<div
  					style={{
  						background: '#fff3cd',
  						padding: '20px',
  						borderRadius: '8px',
  						marginBottom: '30px',
  						border: '2px solid #ffc107',
  						boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
  					}}
  				>
  					<h3 style={{ marginTop: 0, display: 'flex', alignItems: 'center' }}>🔍 環境情報</h3>
  					<table
  						style={{
  							width: '100%',
  							borderCollapse: 'collapse',
  							background: 'white',
  							borderRadius: '5px',
  							overflow: 'hidden',
  						}}
  					>
  						<tbody>
  							<tr>
  								<td
  									style={{
  										padding: '12px',
  										border: '1px solid #ddd',
  										fontWeight: 'bold',
  										background: '#f8f9fa',
  									}}
  								>
  									モード
  								</td>
  								<td style={{ padding: '12px', border: '1px solid #ddd' }}>
  									<code
  										style={{
  											background: '#e9ecef',
  											padding: '2px 8px',
  											borderRadius: '3px',
  										}}
  									>
  										{env.MODE}
  									</code>
  								</td>
  							</tr>
  							<tr>
  								<td
  									style={{
  										padding: '12px',
  										border: '1px solid #ddd',
  										fontWeight: 'bold',
  										background: '#f8f9fa',
  									}}
  								>
  									API URL
  								</td>
  								<td style={{ padding: '12px', border: '1px solid #ddd' }}>{apiUrl}</td>
  							</tr>
  							<tr>
  								<td
  									style={{
  										padding: '12px',
  										border: '1px solid #ddd',
  										fontWeight: 'bold',
  										background: '#f8f9fa',
  									}}
  								>
  									環境名
  								</td>
  								<td style={{ padding: '12px', border: '1px solid #ddd' }}>{envName}</td>
  							</tr>
  							<tr>
  								<td
  									style={{
  										padding: '12px',
  										border: '1px solid #ddd',
  										fontWeight: 'bold',
  										background: '#f8f9fa',
  									}}
  								>
  									本番ビルド
  								</td>
  								<td style={{ padding: '12px', border: '1px solid #ddd' }}>
  									{env.PROD ? '✅ はい' : '❌ いいえ'}
  								</td>
  							</tr>
  							<tr>
  								<td
  									style={{
  										padding: '12px',
  										border: '1px solid #ddd',
  										fontWeight: 'bold',
  										background: '#f8f9fa',
  									}}
  								>
  									開発モード
  								</td>
  								<td style={{ padding: '12px', border: '1px solid #ddd' }}>
  									{env.DEV ? '✅ はい' : '❌ いいえ'}
  								</td>
  							</tr>
  						</tbody>
  					</table>
  				</div>
  			)}
  		</div>
  	);
  }
  
  export default App;
  
  

  ◆ローカル開発（npm run dev）

npm run devでサーバーを起動すると、画面の表示内容から、.env + .env.developmentファイルが読み込まれていることがわかります。

なので、ローカル開発ができることになります。

◆dev・staging環境（npm run dev:staging）

npm run dev:stagingでサーバー起動すると、画面の表示内容から、.env + .env.stagingファイルが読み込まれていることがわかります。

なので、dev・staging環境のAPIを叩いて開発できることになります。

◆dev・staging環境（npm run build:staging と npm run preview）

npm run build:stagingは、staging（dev）環境にデプロイする時に使います。

stagingサーバーにデプロイする前にnpm run build:stagingでビルドします。

そうすると、distフォルダにstagingのAPIパスでビルドされたファイルが出力されます。

その後にnpm run previewでstagingビルドが正しく動くかローカルで確認する時に使います。

具体的なワークフローとして、以下のようになります。

• ローカル開発
  • npm run dev → 動作確認
• stagingにデプロイ前
  • npm run build:staging
  • npm run preview → ビルド結果をローカルで確認。問題なければstagingサーバーにデプロイ
• 本番にデプロイ前
  • npm run build
  • npm run preview → ビルド結果をローカルで確認。問題なければ本番サーバーにデプロイ

npm run build:stagingとnpm run previewを実行すると、以下のように表示されます。

.env + .env.stagingファイルが読み込まれている事がわかりますが、さらにPROD: trueで本番ビルドされていることがわかります。

◆本番ビルド（npm run build と npm run preview）

npm run build と npm run previewを実行すると、以下のように表示されます。

デバッグ情報が表示されていないので、showDebugがfalseになっている事がわかります。

.env + .env.productionが読み込まれていることがわかります。