Next.js CORS 에러 해결법: 로컬 환경부터 Vercel 배포까지

 

"어? 포스트맨(Postman)에서는 잘 되는데 왜 브라우저만 오면 에러가 나지?" 프론트엔드 개발자들의 영원한 숙적, 악명 높은 CORS 에러! Next.js와 React 로컬 환경부터 Vercel 배포까지 완벽하게 대처하는 프록시(Proxy) 및 헤더 설정법을 아주 쉽게 알려드립니다.

 

웹 개발을 처음 시작하고 오픈 API를 연결해서 멋진 화면을 만들려던 찰나, 브라우저 개발자 도구 콘솔창에 시뻘건 글씨로 has been blocked by CORS policy라는 에러 메시지가 뜬 적 있으신가요? 진짜 이 메시지 볼 때마다 심장이 철렁하고 완전 짜증이 솟구치죠. 저도 신입 시절에 이 에러 하나 잡겠다고 밤을 꼴딱 새운 쓰라린 기억이 있답니다. 😭

백엔드 개발자 친구한테 "서버 안 되는데?"라고 물어봤다가 "포스트맨으로는 잘만 되는데 네 코드가 이상한 거 아냐?"라는 답변을 들으면 억울하기 짝이 없죠. 하지만 걱정 마세요! 이 에러는 여러분의 코드가 틀렸거나 서버가 고장 난 게 아니라, 브라우저의 아주 정상적이고 엄격한 보안 시스템이 작동하고 있을 뿐이랍니다. 오늘 제가 로컬(Localhost) 환경부터 실제 Vercel 배포 환경까지 CORS 에러를 깔끔하게 우회하고 해결하는 마법 같은 방법을 알려드릴게요. 끝까지 읽어보시면 앞으로 CORS는 두렵지 않으실 거예요! 😊

 

1. 도대체 CORS가 뭐길래 날 괴롭힐까? 🤔

해결책을 알아보기 전에 적을 먼저 알아야겠죠? CORS(Cross-Origin Resource Sharing)는 우리말로 '교차 출처 리소스 공유'라는 뜻입니다. 이름이 너무 어렵죠? 쉽게 풀어서 설명해 드릴게요.

브라우저는 기본적으로 '동일 출처 정책(SOP)'이라는 규칙을 따릅니다. 즉, 내 프론트엔드 주소가 http://localhost:3000이라면, 데이터를 받아오는 API 서버 주소도 똑같이 http://localhost:3000이어야만 데이터를 안전하다고 믿고 넘겨줍니다. 그런데 우리가 외부 날씨 API(예: https://api.weather.com)에 데이터를 달라고 하면, 브라우저가 중간에 끼어들어서 "잠깐! 주소가 다른데? 해킹일 수도 있으니까 차단할게!" 하고 막아버리는 겁니다.

💡 핵심 포인트!
포스트맨(Postman)은 브라우저가 아니기 때문에 이 보안 정책을 쿨하게 무시하고 데이터를 잘 받아옵니다. 오직 크롬, 사파리 같은 웹 브라우저에서만 발생하는 방어막이라고 생각하시면 돼요.

 

2. 로컬 환경 (Localhost) 해결법: Proxy 설정 🛠️

백엔드 서버의 코드를 우리가 직접 수정할 수 있다면 헤더에 Access-Control-Allow-Origin: *를 추가해 주면 끝납니다. 하지만 외부 공공 API를 쓸 때는 우리가 서버를 건드릴 수 없죠? 이럴 땐 프론트엔드에서 프록시(Proxy)라는 중간 다리를 놔서 브라우저를 속여야 합니다.

프레임워크	해결 방법 및 파일 위치
CRA (React)	package.json 파일 최하단에 "proxy": "https://외부API주소.com" 한 줄 추가. 또는 http-proxy-middleware 라이브러리 사용.
Next.js	next.config.js 파일의 rewrites() 함수 활용 (가장 추천!)

요즘 대세인 Next.js 환경에서의 코드를 살펴볼까요? 프로젝트 최상단에 있는 next.config.js 파일을 열고 아래처럼 작성해 보세요.

module.exports = {
  async rewrites() {
    return [
      {
        source: "/api/:path*", // 내 프론트에서 호출할 가짜 주소
        destination: "https://진짜-외부-api-주소.com/:path*", // 실제 데이터가 있는 곳
      },
    ];
  },
};

이렇게 설정해 두고 프론트엔드 코드(axios나 fetch)에서는 https://진짜... 대신 /api/users 처럼 호출하면, Next.js가 중간에서 목적지로 주소를 싹 바꿔서 데이터를 가져와 줍니다. 브라우저는 "오, 같은 localhost에서 데이터가 왔네?" 하고 속아 넘어가는 거죠!

⚠️ 주의하세요! (서버 재시작 필수)
next.config.js나 package.json 같은 설정 파일을 수정했다면, 반드시 실행 중인 개발 서버(npm run dev)를 끄고 다시 시작해야 프록시가 정상적으로 적용됩니다.

 

3. Vercel 배포 시 발생하는 에러 대처법 🚀

로컬에서는 프록시 덕분에 신나게 개발을 마쳤습니다. 기쁜 마음으로 Vercel(버셀)에 배포를 딱 했는데, 웬걸? 배포된 링크로 들어가 보니 또 다시 CORS 에러가 뿜어져 나옵니다. "아니, 왜 배포하니까 또 안 돼?!" 하면서 뒷목 잡으신 분들 많으실 거예요.

이유는 간단합니다. 로컬 개발 환경과 실제 배포된 서버의 동작 방식이 다르기 때문입니다. 특히 Vercel 같은 Serverless 환경에서는 별도의 헤더(Header) 설정을 명시적으로 해줘야 외부 API와의 통신이 원활해집니다.

🔧 Vercel CORS 헤더 자동 생성기

Next.js 프로젝트를 배포할 때 next.config.js에 추가해야 할 headers() 코드를 자동으로 만들어 드립니다.

허용할 오리진 (Origin):

생성기에서 나온 코드를 기존의 rewrites() 코드와 합쳐서 next.config.js에 넣어주면, Vercel 배포 환경에서도 브라우저가 "아, 이 사이트는 안전한 헤더를 가지고 있구나!" 하고 얌전하게 데이터를 통과시켜 줍니다. 제 생각엔 이 방법이 Next.js + Vercel 조합에서 가장 깔끔한 정석인 것 같아요.

핵심 요약 📝

🛡️

CORS 에러 완벽 방어 요약 노트

1. 원인 파악: CORS는 API 문제가 아닌 브라우저의 자체적인 보안 정책입니다. (Postman과 다름)

2. 로컬(Local) 해결법: Next.js의 경우 next.config.js에

rewrites()

옵션을 추가하여 프록시 우회를 설정합니다.

3. 배포(Vercel) 해결법: 배포 시에는 프록시 대신 headers() 옵션을 추가하여 Access-Control-Allow-Origin을 허용해야 합니다.

4. 잊지 마세요!: 설정 파일을 수정한 후에는 반드시 개발 서버(서버)를 껐다가 다시 켜야 반영됩니다.

더 이상 빨간색 에러 메시지에 당황하지 마세요!

 

자주 묻는 질문 ❓

Q: 프론트엔드에서 모든 CORS 문제를 다 해결할 수 있나요?

A: 안타깝게도 아닙니다. 외부 API 자체가 브라우저 요청을 엄격하게 차단하도록 설계되어 있다면 프론트엔드 프록시로도 뚫기 어려울 수 있습니다. 이럴 때는 어쩔 수 없이 내 백엔드 서버(Node.js 등)를 하나 거쳐서 데이터를 가져오는 '서버 우회' 방식을 써야 합니다.

Q: 크롬 확장 프로그램으로 CORS 끄는 거 쓰면 안 되나요?

A: 혼자서 개발하고 테스트할 때 임시방편으로는 쓸 수 있습니다. (예: Allow CORS 확장 프로그램). 하지만 실제 사용자들은 그 프로그램을 깔고 접속하지 않기 때문에, 배포 시에는 반드시 코드 단에서 프록시나 헤더 설정을 해주어야 합니다.

Q: Vercel 말고 Netlify, AWS 배포 시에도 같은 방법인가요?

A: Next.js 코어 기능인 next.config.js 설정은 동일하게 적용됩니다. 다만 Netlify는 netlify.toml, AWS CloudFront는 응답 헤더 정책(Response Headers Policy)에서 추가적으로 설정이 필요할 수 있습니다.

매번 우리를 괴롭히던 CORS 에러, 오늘 정리해 드린 프록시와 헤더 설정법으로 이제는 쿨하게 이겨내실 수 있겠죠? 이 글이 여러분의 퇴근 시간을 조금이나마 앞당겨 주기를 바랍니다. 혹시 적용하시다가 막히는 부분이나 추가로 궁금한 점이 있다면 언제든지 댓글로 남겨주세요~ 😊