ViteのproxyでReactから別ポートのAPIを呼ぶ方法
Vite の設定ファイルに server.proxy を書くと、React の画面から fetch('/api/items') のように相対パスで呼んだリクエストを、開発サーバーが別のポートの API サーバーへ転送してくれます。開発中に localhost:5173 の画面から localhost:3000 の API を呼ぶと CORS エラーで止まりますが、proxy を通せば API 側に CORS の設定を足さなくても呼べます。
私は検証環境で、Node.js で書いた小さな API サーバーを用意し、文字列だけの書き方、changeOrigin、rewrite を順に試しました。API サーバーが受け取ったパスと Host ヘッダーを応答に入れて、転送の中身を確かめています。
検証環境は Ubuntu 24.04、Node.js 22.23.4、Vite 8.3.8、@vitejs/plugin-react 6.3.0、React 19.3.1、TypeScript 7.0.2 です。プロジェクトは npm create vite@latest の react-ts テンプレートで作り、画面は Playwright 1.63.0 の Chromium で開き、ビルド後の確認には Python 3.11.18 の http.server も使いました。API サーバーはすべて同じマシンの上で動かしています。WebSocket の転送(ws: true)、HTTPS の API への転送、Cookie を使うログイン、本番用の Web サーバー(nginx など)での設定は試していません。
proxy なしで別ポートの API を呼ぶと CORS エラーになる
まず比べるために、http://localhost:5173 で開いた画面の中から、http://localhost:3000/api/items を直接 fetch しました。ブラウザのコンソールには次のエラーが出て、fetch は TypeError: Failed to fetch で失敗しました。
Access to fetch at 'http://localhost:3000/api/items' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
ポート番号が違うと、別のオリジンとして扱われます。MDN の CORS の説明にあるとおり、fetch() は同一オリジンポリシーに従うので、別のオリジンの応答は、正しい CORS のヘッダーが付いていないと画面のコードから読めません。
proxy を使うと、ブラウザがやり取りする相手は画面と同じ localhost:5173 だけになります。API サーバーとやり取りするのは Vite の開発サーバーです。
vite.config.ts に server.proxy を書く
いちばん短い書き方は、キーにパスの先頭、値に転送先の URL を書く形です。
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
server: {
proxy: {
// /api で始まるリクエストを、API のサーバーに転送する
'/api': 'http://localhost:3000',
},
},
})
React のコンポーネントからは、ホスト名もポートも書かずに相対パスで呼びます。
// src/App.tsx(一部)
const API_URL = '/api/items'
useEffect(() => {
fetch(API_URL)
.then(async (res) => {
if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
return (await res.json()) as ItemsResponse
})
.then(setData)
.catch((e: unknown) => setError(String(e)))
}, [])
開発サーバー(npm run dev で起動するもの)で開くと、API サーバーの返した一覧が表示されました。API サーバーには、パス /api/items のまま届いています。

curl で開発サーバーに /api/items を送っても、API サーバーの JSON がそのまま返りました(-i で表示した応答ヘッダーは省いています)。
$ curl -s -i http://localhost:5173/api/items
{"items":["りんご","みかん","ぶどう"],"receivedPath":"/api/items","host":"localhost:3000","origin":null}
キーは「パスの先頭が一致するか」で判定される
Vite の server.proxy の説明には、パスがキーで始まるリクエストを転送すると書かれています。/api で始まれば、区切りの / がなくても対象です。
検証環境で、開発サーバーに curl で /apidocs を送ると、このリクエストも 3000 番の API サーバーに届き、API サーバーの 404 の JSON が返りました。
$ curl -s http://localhost:5173/apidocs; echo
{"error":"not found","receivedPath":"/apidocs"}
画面のルーティングで /api で始まるパスを使うと、そのパスも API サーバーへ転送されます。キーは、画面のパスと先頭が重ならない名前にします。公式ドキュメントによると、キーを ^ で始めると正規表現として扱われます。
changeOrigin で Host ヘッダーが変わる
転送先をオブジェクトで書くと、オプションを足せます。changeOrigin を書かずに次の設定で起動すると、API サーバーが受け取った Host ヘッダーは localhost:5173(開発サーバーのもの)でした。
proxy: {
'/api': {
target: 'http://localhost:3000',
},
},
changeOrigin: true を足すと、Host ヘッダーは localhost:3000 になりました。
proxy: {
'/api': {
target: 'http://localhost:3000',
// API のサーバーに送る Host ヘッダーを、転送先のものに変える
changeOrigin: true,
},
},
Vite の server.proxy の説明にあるとおり、Vite の proxy は http-proxy-3 を使っています。http-proxy-3 のオプションの説明によると、changeOrigin の初期値は false です。ただし、最初に書いた文字列だけの書き方では、Host は localhost:3000 になっていました。Vite 8.3.8 のコードでは、値が文字列のとき { target: 値, changeOrigin: true } に置き換えられます。オブジェクトの書き方に変えたときだけ、changeOrigin を自分で書く必要があります。
API のパスに /api がないときは rewrite で取る
API サーバーが /items で応答し、パスに /api が付いていない場合を試しました。3001 番で動かした API サーバーに、changeOrigin だけの設定で転送すると、/api/items がそのまま届き、404 が返りました。画面には「読み込みに失敗しました:Error: 404 Not Found」と出ます。
rewrite に、転送する前のパスを書き換える関数を渡すと直りました。
proxy: {
'/api': {
target: 'http://localhost:3001',
changeOrigin: true,
// 転送する前に、パスの先頭の /api を取る
rewrite: (path) => path.replace(/^\/api/, ''),
},
},
API サーバーのログ(一部)でも、届くパスが /api/items から /items に変わったことを確かめました。
[backend:3001] GET /api/items host=localhost:3001 origin=-
[backend:3001] GET /items host=localhost:3001 origin=-

画面のコードは /api/items のままで、変えていません。画面のコードの側では「/api で始まるのは API」と決めておき、実際の API のパスとの違いは vite.config.ts だけで吸収できます。この設定を足しても、npx tsc -b の型チェックはエラーなく通りました。
API サーバーが止まっていると 502 が返る
API サーバーを止めたまま画面を開くと、開発サーバーは 502 Bad Gateway を返し、画面には「読み込みに失敗しました:Error: 502 Bad Gateway」と出ました。開発サーバーを起動したターミナルには、次のログ(一部)が出ています。
4:20:30 AM [vite] http proxy error: /items
Error: connect ECONNREFUSED 127.0.0.1:3001
Node.js のエラーの説明によると、ECONNREFUSED は接続先に拒否されたことを表し、多くは相手側のサービスが動いていないときに起きます。検証環境でも、3001 番に直接 curl で接続すると失敗しました。ログのパスは rewrite で書き換えた後の /items になっています。画面で 502 が出たら、まずこのログと、API サーバーが起動しているかを確かめます。
ビルドした後は proxy がない
Vite の説明にあるとおり、server.proxy は開発サーバーのための設定です。npm run build で作った dist/ を、Python の簡単な静的サーバー(python3 -m http.server)で配信して開くと、/api/items は 404 になり、画面には「読み込みに失敗しました:Error: 404 File not found」と出ました。ビルドしたファイルの中に、転送の仕組みは入りません。
本番でも /api を相対パスで呼ぶなら、画面を配信する Web サーバーの側で、同じ転送の設定が必要です。server.proxy を書いただけでは、本番の画面から API は呼べません。
一方、同じ dist/ を vite preview で開くと、API の一覧が表示されました。preview.proxy の説明のとおり、preview.proxy を書かなければ server.proxy と同じ設定が使われます。ただし、公式ドキュメントの静的サイトのデプロイのページには、vite preview は手元でビルドを確かめるためのもので、本番のサーバーとして使うものではないと書かれています。





