Proxy

Vite 프록시(Proxy) 설정 가이드

1. 프록시(Proxy)란?

프록시는 클라이언트와 서버 사이에서 요청을 중계하는 중간 서버입니다.

[브라우저]  →  [Vite Dev Server (프록시)]  →  [백엔드 API 서버]
 :5173              :5173/api/...                  :8080
Plain Text
복사

왜 프록시가 필요한가? - CORS 문제

브라우저는 동일 출처 정책(Same-Origin Policy) 에 의해 다른 도메인/포트로의 요청을 차단합니다.

항목	프론트엔드	백엔드
주소	http://localhost:5173	http://localhost:8080
포트	5173	8080
결과	출처(Origin)가 다름 → CORS 에러 발생

프록시를 사용하면: 브라우저는 같은 포트(5173)로 요청하므로 CORS 문제가 발생하지 않습니다.

브라우저 → /api/member/list (5173) → Vite가 8080으로 전달 → 응답 반환
Plain Text
복사

2. Vite 프록시 기본 설정

vite.config.js 파일의 server.proxy 옵션으로 설정합니다.

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  server: {
    proxy: {
      '/api': {                              // ① 프록시 경로 접두사
        target: '<http://localhost:8080>',     // ② 실제 백엔드 서버 주소
        changeOrigin: true,                  // ③ Origin 헤더 변경
        rewrite: (path) => path.replace(/^\\/api/, ''),  // ④ 경로 재작성
        configure: (proxy) => {             // ⑤ 추가 설정
          proxy.on('proxyReq', (proxyReq) => {
            proxyReq.removeHeader('origin')  // Origin 헤더 제거
          })
        }
      }
    }
  }
})
JavaScript
복사

3. 설정 옵션 상세 설명

① 프록시 경로 접두사 (/api)

'/api': { ... }
JavaScript
복사

•

/api로 시작하는 모든 요청을 이 프록시 규칙으로 처리합니다.

•

예: /api/member/list, /api/board/write 등

② target - 백엔드 서버 주소

target: '<http://localhost:8080>'
JavaScript
복사

•

실제 API 요청을 전달할 백엔드 서버의 주소입니다.

•

개발 환경에서는 보통 로컬 스프링부트 서버 주소를 사용합니다.

③ changeOrigin - Origin 헤더 변경

changeOrigin: true
JavaScript
복사

값	동작
true	Host 헤더를 target 서버의 주소로 변경
false (기본)	원래 Host 헤더(localhost:5173) 유지

•

CORS 처리 시 거의 항상 true로 설정합니다.

•

백엔드 서버가 Host 헤더를 검증할 때 필요합니다.

④ rewrite - 경로 재작성

rewrite: (path) => path.replace(/^\\/api/, '')
JavaScript
복사

브라우저 요청 URL	백엔드 전달 URL
/api/member/list	/member/list
/api/board/write	/board/write
/api/login	/login

•

앞의 /api 접두사를 제거한 뒤 백엔드로 전달합니다.

•

백엔드 API 경로에 /api가 없는 경우 사용합니다.

rewrite 사용 여부 비교

rewrite 있는 경우:  /api/member/list → /member/list    (접두사 제거)
rewrite 없는 경우:  /api/member/list → /api/member/list (그대로 전달)
Plain Text
복사

⑤ configure - 프록시 이벤트 훅

configure: (proxy) => {
  proxy.on('proxyReq', (proxyReq) => {
    proxyReq.removeHeader('origin')
  })
}
JavaScript
복사

•

http-proxy 라이브러리의 이벤트를 직접 제어할 수 있습니다.

•

proxyReq: 백엔드로 나가는 요청을 가로채는 이벤트

removeHeader('origin')이 필요한 이유

일부 백엔드 서버(Spring Security 등)가 Origin 헤더를 엄격하게 검사합니다.

changeOrigin: true 만으로 해결되지 않을 때, Origin 헤더 자체를 제거하면

백엔드가 CORS 검사를 우회하게 됩니다.

Origin 헤더 있을 때: 백엔드가 CORS 정책 검사 → 거부 가능
Origin 헤더 제거:    백엔드가 일반 HTTP 요청으로 인식 → 허용
Plain Text
복사

4. 요청 흐름 전체 예시

① 컴포넌트에서 fetch('/api/member/list') 호출
         ↓
② Vite Dev Server가 '/api' 패턴 감지
         ↓
③ rewrite: '/api/member/list' → '/member/list'
         ↓
④ changeOrigin: Host 헤더를 'localhost:8080'으로 변경
         ↓
⑤ configure: Origin 헤더 제거
         ↓
⑥ '<http://localhost:8080/member/list>' 로 요청 전달
         ↓
⑦ 스프링부트 서버 처리 후 응답 반환
         ↓
⑧ Vite가 브라우저로 응답 전달
Plain Text
복사

5. React 코드에서 API 호출 방법

프록시 설정 후에는 전체 URL 대신 상대 경로만 사용합니다.

// ❌ 잘못된 방법 - 직접 백엔드 주소 사용 (CORS 에러)
const res = await fetch('<http://localhost:8080/member/list>');

// ✅ 올바른 방법 - 상대 경로 사용 (Vite 프록시가 중계)
const res = await fetch('/api/member/list');
JavaScript
복사

axios 사용 시

// axios 기본 설정 (baseURL 설정 불필요)
import axios from 'axios';

// 요청 예시
const res = await axios.get('/api/member/list');
const res = await axios.post('/api/member/login', { id, pwd });
JavaScript
복사

6. 다중 프록시 설정

여러 경로에 대해 각각 다른 서버로 프록시할 수 있습니다.

server: {
  proxy: {
    '/api': {
      target: '<http://localhost:8080>',  // 메인 백엔드
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\\/api/, '')
    },
    '/auth': {
      target: '<http://localhost:9090>',  // 인증 서버
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\\/auth/, '')
    },
    '/upload': {
      target: '<http://localhost:8080>',  // 파일 업로드
      changeOrigin: true,
    }
  }
}
JavaScript
복사

7. 개발 vs 운영 환경

프록시 설정은 개발 환경에서만 동작합니다.

환경	방법
개발 (npm run dev)	Vite 프록시 사용
운영 (npm run build 후 배포)	Nginx 리버스 프록시 또는 백엔드 CORS 설정

운영 환경 Nginx 예시

location /api/ {
    proxy_pass <http://backend:8080/>;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
Plain Text
복사

8. 트러블슈팅

증상	원인	해결 방법
CORS error 계속 발생	프록시 경로 불일치	fetch('/api/...') 경로와 프록시 키('/api') 확인
404 Not Found	rewrite 설정 오류	백엔드 실제 경로와 rewrite 결과 비교
401 Unauthorized	Origin 헤더 문제	configure에서 removeHeader('origin') 추가
프록시 적용 안 됨	절대 URL 사용	http://localhost:8080/... → /api/... 로 변경
설정 변경 미적용	Vite 서버 미재시작	npm run dev 재실행

핵심 정리

프록시 = CORS 문제를 개발 환경에서 우회하는 도구

/api/* 요청  →  Vite Dev Server  →  <http://localhost:8080/*>
(브라우저)        (중간 중계자)         (Spring Boot)

설정 위치: vite.config.js > server > proxy
호출 방법: fetch('/api/경로') — 절대 URL 사용 금지
Plain Text
복사