Vite の dev server proxy が機能しない

要約

Vite の dev server で server.proxy を設定したのに転送されない場合、リクエストパスがキーにマッチしていない、changeOrigin が抜けている、もしくはクライアントが絶対 URL を叩いていて proxy を経由していない、のいずれかがほとんどです。
ブラウザの Network タブで「Request URL」と「Status」を確認すれば原因はすぐ絞れます。

よくある原因

1. server.proxy のキー（例: /api）とリクエストパスがマッチしていない
2. ターゲットが HTTPS や別ホストで changeOrigin: true を指定していない
3. rewrite で prefix を取り除く設定を忘れており、ターゲット側で 404 になっている
4. クライアントから絶対 URL を直接叩いており、Vite を経由していない

解決策

1. プレフィックスと相対パスを合わせる

import { defineConfig } from "vite";
 
export default defineConfig({
  server: {
    proxy: {
      "/api": {
        target: "http://localhost:8080",
        changeOrigin: true,
      },
    },
  },
});

クライアント側も相対パスで呼びます。

fetch("/api/users").then((r) => r.json());

絶対 URL（http://api.example.com/users）でリクエストすると Vite を経由せず、proxy 設定は適用されません（公式ドキュメント）。

2. 別ホスト・HTTPS は changeOrigin を付ける

changeOrigin: true を指定すると Vite がリクエストの Host ヘッダをターゲット側に書き換え、ホスト名検査を通過できます。

proxy: {
  "/api": {
    target: "https://api.example.com",
    changeOrigin: true,
  },
}

3. プレフィックスを除去する

ターゲット側が /api を含まない URL（/users）を期待するなら rewrite で除去します。

proxy: {
  "/api": {
    target: "http://localhost:8080",
    changeOrigin: true,
    rewrite: (path) => path.replace(/^\/api/, ""),
  },
}

4. Network タブで実際の URL を確認する

ブラウザの DevTools → Network で対象リクエストを選び、「Request URL」が http://localhost:5173/api/... になっているかを確認します。5173 以外のホストなら proxy を経由していません。
プレビュー時（vite preview）には server.proxy は適用されない点にも注意します。