できない.dev

Vite の dev server proxy が機能しない

Vite の server.proxy が効かないときは、リクエストのパスをキーに合わせ、changeOrigin: true を付ければたいてい直る。
絶対 URL を叩くと proxy を通らないので、Network タブで実際の URL を確かめる。

公開: 更新:

症状できない
curl -s -w '\n%{http_code}\n' http://localhost:5173/api/users
backend: not found /api/users
404
解決後できた
curl -s -w '\n%{http_code}\n' http://localhost:5173/api/users
[{"id":1,"name":"alice"}]
200

2026-10-08 に node:20(Vite 8.3.3 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

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

実行例

server.proxy のキーを /apis にしたままだと /api/users は転送されず、開発サーバーが index.html を 200 で返した。
キーを /api に直しても rewrite が無いと、バックエンドは /api/users を受け取って 404 を返している。
rewrite で /api を取り除くと、バックエンドには /users が届いて JSON が返った。

$ curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://localhost:5173/api/users
200 text/html
$ curl -s -w '\n%{http_code}\n' http://localhost:5173/api/users
backend: not found /api/users
404
$ cat backend.log
backend got: GET /api/users
$ curl -s -w '\n%{http_code}\n' http://localhost:5173/api/users
[{"id":1,"name":"alice"}]
200
$ cat backend.log
backend got: GET /api/users
backend got: GET /users

— 2026-10-08 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-08 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • Vite 8.3.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

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 は適用されない点にも注意する。

よくある原因

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