はじめに：ハードコーディングされた `vite.config.ts` という「負債」からの脱却
チーム開発において、フロントエンドとバックエンドの結合段階で以下のような不毛なやり取りが発生していないだろうか。
> 「ローカルのAPIサーバーのポート、君は3000番？こっちはGoだから8080番なんだけど」
> 「Staging環境に向けるときのプロキシ設定、誰か`vite.config.ts`直書きしたままコミットしてない？」
> 「Docker環境とローカルホスト直接起動で、毎回コンフィグ書き換えるの面倒くさすぎない？」
`vite.config.ts` の `server.proxy` に、以下のようなハードコーディングされた設定を見かけるたび、私はアーキテクトとして密かに頭を抱えている。
// ❌ 絶望的にスケーラビリティのないアンチパターン
export default defineConfig({
server: {
proxy: {
‘/api’: ‘http://localhost:8080’, // 開発者Aの環境専用、Dockerや別ポートの人は死亡
}
}
})
本記事では、開発者のPC環境、ブランチ、環境変数、さらにはDockerネットワークやクラウド上の動的プレビュー環境までを自動検知し、Viteのプロキシサーバーを完全に動的に構築・ルーティングする次世代のオート設定機構を解説する。
単なる「公式ドキュメントのコピペ」ではない。実務の泥臭いカオスを優雅に解決する、テックリード必携の実装コードを叩き込む。
—
1. なぜ「動的プロキシ」が必要なのか？（アーキテクチャの思想）
現代のWeb開発において、フロントエンド開発者が依存するバックエンドは単一ではない。
- ローカルのネイティブプロセスで動くAPI
- Docker Composeで立ち上がったマイクロサービス群
- PR（プルリクエスト）ごとに乱立する Ephemeral（使い捨て）なStaging環境
これらをハードコーディングで乗り切ろうとすると、Gitのコンフリクト地獄と、環境差異による「私のローカルでは動くのに」という不毛なバグ報告の温床になる。
Viteの `server.proxy` は、実は単なるオブジェクトだけでなく、関数（Requestをフックして動的にルーティング先を決定する仕組み）、さらには設定ファイル自体をTypeScriptでプログラマブルに構築するアプローチを完全にサポートしている。
この仕組みを最大化し、「環境変数を読み取り、宛先を自動解決し、さらに接続先が生きていなければフォールバックする」動的プロキシ層をViteの内部にインジェクションする。
—
2. 実装：環境自動検知型 `vite.config.ts` の全貌
それでは、実際のプロジェクトに即した最高峰の設定ファイルを公開しよう。
このコードは、以下の条件を自動で判定・解決する。
1. `.env` やシステム環境変数からバックエンドの基底URLを動的構築
2. Docker環境（`DOCKER_ENV=true`）の場合は内部ネットワークのホスト名へ自動スイッチ
3. 複数存在するAPIドメイン（Auth系、Core系）のルーティングをプレフィックスベースで動的生成
`vite.config.ts` のベストプラクティス実装
import { defineConfig, loadEnv, UserConfig } from ‘vite’
import react from ‘@vitejs/plugin-react’ // 例としてReactを使用
import { execSync } from ‘child_process’
import dns from ‘dns’
// Node.jsのDNS解決においてローカルホストの解決順序を最適化（Vite起動の高速化）
dns.setDefaultResultOrder(‘verbatim’)
/
- 現在のGitブランチ名を取得し、PR環境などの特殊ルーティングが必要か判定する
/
const getCurrentBranch = (): string => {
try {
return execSync(‘git rev-parse –abbrev-ref HEAD’).toString().trim()
} catch {
return ‘unknown’
}
}
/
- 動的プロキシのルーティング先を決定する核心ロジック
/
const resolveBackendTarget = (mode: string): string => {
// 指定されたモード（development, staging等）に応じた環境変数をロード
const env = loadEnv(mode, process.cwd(), ”)
// 1. 明示的に環境変数が指定されている場合はそれを最優先
if (env.VITE_OVERRIDE_API_URL) {
console.log(`[Vite Proxy] Overriding API target with: ${env.VITE_OVERRIDE_API_URL}`)
return env.VITE_OVERRIDE_API_URL
}
// 2. Dockerコンテナ内からの実行を検知した場合のフォールバック
if (process.env.DOCKER_ENV === ‘true’) {
console.log(‘[Vite Proxy] Detected Docker environment. Routing to backend container.’)
return ‘http://backend-api:8080’
}
// 3. Gitの特定のfeatureブランチに応じた動的ルーティング（例：検証環境への直結）
const branch = getCurrentBranch()
if (branch.startsWith(‘feature/heavy-api’)) {
console.log(`[Vite Proxy] Branch ‘${branch}’ detected. Routing to heavy-mock server.`)
return ‘https://mock-api.internal.company.com’
}
// 4. デフォルトのローカル開発サーバー
const defaultPort = env.BACKEND_PORT || ‘3000’
return `http://localhost:${defaultPort}`
}
export default defineConfig(({ mode }): UserConfig => {
// 動的に決定されたバックエンドのオリジン
const apiTarget = resolveBackendTarget(mode)
return {
plugins: [
react(),
// 開発効率を劇的に高める神プラグイン群（後述）
],
server: {
host: true, // 外部からのアクセス（スマホ実機検証など）を許可
port: 5173,
strictPort: true, // ポートが競合した際に勝手にインクリメントさせずエラーにする（CI/CDやスクリプト連携のため）
proxy: {
// ‘/api’ で始まるリクエストを動的ターゲットへプロキシ
‘^/api’: {
target: apiTarget,
changeOrigin: true, // ホストヘッダーをターゲットのドメインに変更（CORS対策の基本）
// パスの書き換え：’/api/v1/users’ -> ‘/v1/users’ に変換してバックエンドへ渡す
rewrite: (path) => path.replace(/^\/api/, ”),
// プロキシエラー時のハンドリング（バックエンドが落ちている時にVite側でクラッシュさせない）
configure: (proxy, _options) => {
proxy.on(‘error’, (err, _req, _res) => {
console.error(‘[Vite Proxy Error] Backend is unreachable:’, err)
})
proxy.on(‘proxyReq’, (proxyReq, req, _res) => {
// デバッグ用にプロキシされたリクエストをコンソールにトレース
console.log(`[Vite Proxy] Incoming Request: ${req.method} ${req.url} -> Target: ${apiTarget}${req.url}`)
})
},
},
// WebSocketなどのリアルタイム通信用プロキシ設定（必要に応じて動的生成）
‘/ws’: {
target: apiTarget.replace(‘http’, ‘ws’),
ws: true,
changeOrigin: true,
}
},
},
}
})
—
3. チーム開発を加速させる設定の共有化ルールと環境変数設計
動的プロキシをチーム全員でシームレスに運用するためには、環境変数の契約（スキーマ）を厳格に定義する必要がある。
`.env.development` のベストプラクティス構成例
プロジェクトルートに配置し、Git管理に含めるデフォルト設定。
==============================================================================
フロントエンド開発環境 共通設定
==============================================================================
デフォルトのバックエンドポート（各開発者は必要に応じて .env.local で上書き可能）
BACKEND_PORT=8080
APIのベースパスプレフィックス
VITE_API_BASE_PATH=/api
【緊急用】強制的に特定のモックサーバーやリモート環境に向ける場合のみコメントアウトを外す
VITE_OVERRIDE_API_URL=https://api-dev.company.com
💡 開発者個人のローカル上書きルール (`.env.local`)
バックエンドのポートが人によって異なる場合（例：Java担当は8080、Go担当は9000など）、`.env.local`（Git管理対象外）を作成し、以下の一行だけを書くルールをチームに徹底させる。
.env.local (Git Ignore対象)
BACKEND_PORT=9000
これだけで、`vite.config.ts` が自動的にポートを検知し、プロキシ先を `http://localhost:9000` に切り替えてくれる。チームメンバー全員が同じコンフィグファイルを修正しながらGitコンフリクトを起こす悪夢から完全に解放される。
—
4. 開発スピードを極限まで引き上げる「神プラグイン」の導入
動的プロキシと組み合わせることで、フロントエンド開発のスピードが爆発的に向上するViteプラグインを厳選して紹介する。
1. `vite-plugin-mkcert` （ローカルHTTPS環境の自動構築）
モダンブラウザのセキュリティ要件（Cookieの `Secure` 属性やWeb Crypto APIなど）により、ローカルでもHTTPSが必須になるケースが増えている。このプラグインを入れるだけで、開発証明書を自動生成し、プロキシを含めた完全なローカルHTTPS環境が手に入る。
npm install -D vite-plugin-mkcert
2. `vite-plugin-checker` （型エラーやリントをバックグラウンドで監視）
ビルド時だけでなく、開発サーバー稼働中にもTypeScriptの型チェックやESLintを別スレッドで並列実行し、オーバーレイ表示させる。プロキシ経由でAPIを叩くコードを書いた瞬間に型ズレを検知できる。
npm install -D vite-plugin-checker
`vite.config.ts` へのプラグイン統合例
import mkcert from ‘vite-plugin-mkcert’
import checker from ‘vite-plugin-checker’
export default defineConfig(({ mode }) => {
return {
plugins: [
// …他のプラグイン
// ローカルHTTPS化（mkcert）
mkcert(),
// 型チェックとLinterのバックグラウンド実行
checker({
typescript: true,
eslint: {
lintCommand: ‘eslint “./src//.{ts,tsx}”‘,
},
}),
],
// …server config
}
})
—
5. 生産性を爆上げするCLIショートカットとスクリプト設計
毎日叩くコマンドは、指に覚え込ませるレベルで最適化する。`package.json` の `scripts` を以下のように設計し、環境に応じた起動をワンタッチで行えるようにする。
`package.json` のベストプラクティス
{
“scripts”: {
“dev”: “vite”,
“dev:docker”: “DOCKER_ENV=true vite –host”,
“dev:staging”: “vite –mode staging”,
“build”: “tsc && vite build”,
“preview”: “vite preview”
}
}
隠れたキーボードショートカット（Vite CLIの操作）
Viteの開発サーバーを立ち上げた状態で、ターミナル上で以下のキーを押すだけで、ブラウザを開かずに様々なアクションを実行できる。
- `r` + `Enter`: サーバーの手動再起動（Cold Reload）
- `u` + `Enter`: ローカルおよびネットワーク上のURLをターミナルに再表示
- `o` + `Enter`: 設定されたブラウザで自動的にアプリを開く
- `h` + `Enter`: ヘルプメニューの表示
特に `r` + `Enter` は、動的プロキシの設定や `.env` の値を書き換えた際に即座に反映させるための必須ショートカットである。ブラウザのリロードすら不要な場面も多い。
—
おわりに：エンジニアリングの「無駄」をコードで駆逐せよ
環境差異による設定ミスの修正、チームメンバーごとのポート番号の衝突、ハードコーディングされたコンフィグの修正コミット……。これらは開発チームのエネルギーを確実に削ぐ「無駄」でしかない。
今回紹介した「動的プロキシ・オート設定機構」を導入することで、`vite.config.ts` は単なる「設定ファイル」から、「環境のゆらぎを吸収するスマートなインフラストラクチャ」へと進化する。
今日からあなたのプロジェクトの `vite.config.ts` をリファクタリングし、チーム全員の開発体験を最高峰の領域へと引き上げよう。技術の力で、開発をもっとエキサイティングなものに。