프론트엔드 개발 시 CORS 에러 해결 방법 - 실무 기반 가이드
목차
CORS란 무엇인가요?
CORS(Cross-Origin Resource Sharing)는 웹 브라우저에서 다른 출처의 리소스를 요청할 때 보안을 위해 발생하는 정책입니다. 예를 들어, https://myfrontend.com에서 https://api.otherserver.com의 데이터를 요청하면 브라우저는 이를 "교차 출처 요청"으로 간주하고, 서버가 명시적으로 허용하지 않으면 에러를 발생시켜요.
이제 실제로 어떤 경우에 에러가 발생하고, 이를 프론트엔드 개발자가 어떻게 대응할 수 있는지 살펴보겠습니다.
CORS 에러가 발생하는 주요 원인
프론트엔드 개발에서 API 호출 시 CORS 에러가 발생하는 주된 이유는 다음과 같습니다:
- 서버에서 CORS 허용 설정이 되어 있지 않음 -
Access-Control-Allow-Origin헤더 미설정 - 브라우저가 preflight 요청(OPTIONS)을 차단 - 특히
PUT,DELETE요청 시 자주 발생 - 프론트엔드 개발 환경과 API 서버의 도메인이 다름 - 로컬 개발 환경에서 가장 흔함
- 쿠키나 인증 정보를 포함한 요청 시 -
credentials: 'include'사용 시 주의 필요
프론트엔드에서의 해결 방법
프론트엔드 개발자가 CORS 에러를 우회하거나 해결할 수 있는 방법은 다음과 같아요:
1. 프록시 서버 활용
로컬 개발 환경에서는 vite.config.js 또는 webpack-dev-server에서 프록시를 설정해 CORS 문제를 우회할 수 있어요.
// vite.config.js 예시
export default defineConfig({
server: {
proxy: {
'/api': {
target: 'https://api.otherserver.com',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, ''),
}
}
}
})2. 서버 측에 CORS 설정 요청
백엔드 개발자와 협업하여 Access-Control-Allow-Origin 헤더를 올바르게 설정하도록 요청해야 합니다. 예: 모든 출처 허용 → Access-Control-Allow-Origin: * 또는 특정 도메인만 허용
3. CORS 프리 요청 피하기
단순 요청(Simple Request)을 활용하면 브라우저의 preflight 요청 없이 호출할 수 있습니다. 예를 들어, Content-Type을 application/json 대신 text/plain으로 설정하는 방식이에요.
chrome --disable-web-security 같은 비권장 옵션을 사용할 수 있지만, 배포 환경에서는 절대 사용하면 안 됩니다!이제 실제 업무에서 CORS 문제를 어떻게 해결했는지 사례를 중심으로 알아볼게요.
실무에서 활용한 실제 해결 사례
제가 최근 참여한 프로젝트 중 하나는 사내 관리 시스템에서 외부 결제 API를 연동하는 작업이었어요. 개발 초기에는 프론트엔드 로컬 서버(localhost:5173)에서 외부 API 호출 시 다음과 같은 CORS 에러가 발생했죠:
Access to fetch at 'https://pay.example.com/api/init' from origin 'http://localhost:5173' has been blocked by CORS policy.이 문제를 해결하기 위해 우선 vite 프록시를 설정했지만, 인증 관련 쿠키가 포함된 요청이었기에 프록시만으로는 부족했어요. 그래서 백엔드와 협의해 다음과 같은 설정을 추가했죠:
Access-Control-Allow-Origin: http://localhost:5173Access-Control-Allow-Credentials: trueAccess-Control-Allow-Headers: Content-Type
추가로 프론트엔드 측에서도 fetch 요청 시 credentials: 'include'를 명시해줘야 했습니다.
fetch('https://pay.example.com/api/init', {
method: 'POST',
credentials: 'include',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({ orderId: 12345 })
})마무리 및 팁
CORS는 보안 측면에서 매우 중요한 정책이지만, 개발 초기에는 자주 혼란을 일으킬 수 있어요. 특히 로컬 개발 환경에서는 프록시 설정으로 대부분의 문제를 해결할 수 있고, 인증 정보가 포함된 경우는 서버 측 협업이 필수적입니다.
또한, 모든 브라우저는 동일한 방식으로 CORS를 처리하지 않기 때문에, 크로스 브라우징 테스트도 함께 진행하는 것이 좋아요. 문제를 빠르게 파악하고 해결하기 위해서는 개발자 도구의 네트워크 탭과 콘솔 로그를 적극 활용해야 합니다.
이제 마지막으로 결론을 정리해 보겠습니다.
결론
프론트엔드 개발에서 CORS 에러는 누구나 한 번쯤 마주치는 문제입니다. 하지만 이를 해결하는 방법은 그렇게 복잡하지 않아요. 문제의 본질을 이해하고, 브라우저와 서버의 역할을 명확히 구분한 뒤 대응 전략을 세운다면 오히려 보안에 대한 감각도 함께 키울 수 있어요.
정리하자면, 프론트엔드 개발자가 할 수 있는 가장 좋은 방법은 프록시 설정, 요청 헤더 최적화, 그리고 백엔드와의 원활한 커뮤니케이션입니다. 특히 협업 과정에서 발생하는 API 연동 이슈는 빠르게 문제를 파악하고 해결안을 제시하는 개발자가 팀의 생산성을 크게 높일 수 있어요.
오늘 정리한 CORS 해결 방법을 기반으로 여러분의 프로젝트에도 잘 적용해 보세요. 그리고 어떤 상황에서 어떤 해결 방법이 적합한지 경험을 쌓아가면서 점점 더 능숙한 프론트엔드 개발자로 성장하길 바랍니다!