CORSCross-Origin Resource Sharing

바이브 코딩 입문 후 처음 만나는 벽 1순위입니다. 콘솔에 Access to fetch ... has been blocked by CORS policy가 뜨면 이 항목입니다.

무슨 일이 일어난 것인가요

브라우저는 localhost:3000에서 열린 내 앱이 api.example.com을 호출하면 — 출처(origin)가 다르므로 — 서버가 명시적으로 허용했는지 확인합니다. 서버 응답에 "그 출처 허용함"(Access-Control-Allow-Origin 헤더)이 없으면 브라우저가 응답을 버립니다. 중요한 사실 두 가지가 있습니다.

1. 막는 주체는 브라우저입니다. 그래서 같은 요청을 서버(백엔드)에서 하면 잘 되고, Postman에서도 잘 됩니다. "포스트맨에선 되는데요?"가 CORS의 시그니처입니다.
2. 고치는 곳은 서버입니다. 프론트엔드 코드를 아무리 고쳐도 해결되지 않습니다.

해결 경로

• 내 서버라면: 서버에서 내 앱의 출처를 허용합니다(프레임워크마다 CORS 설정 한 줄).
• 남의 API라면: 내 백엔드(API 라우트)가 대신 호출하고 결과를 프론트에 넘기는 프록시 패턴이 정석입니다. API 키도 숨겨지는 부수 효과가 있습니다.
• 브라우저 보안 끄기, 아무 출처나 허용(*)하고 배포 — 둘 다 하지 않습니다.

AI에게 시키기

브라우저에서 외부 API를 직접 fetch하니 CORS 에러가 나.
Next.js API 라우트로 프록시를 만들어서 서버가 대신 호출하게 바꿔줘.
API 키는 프론트에 노출되지 않게 서버 환경변수에서 읽고.

"CORS 에러 고쳐줘"라고만 하면 AI가 프론트 코드를 헛수정하는 경우가 많습니다. 프록시로 우회라는 방향을 지정하면 한 번에 갑니다.

혼동 주의

• 네트워크 오류가 아닙니다. 요청은 서버까지 갔고 응답도 왔습니다. 브라우저가 응답을 읽지 못하게 막은 것입니다.
• 인증 실패(401·403)와 다릅니다. 그것은 서버가 "너 누구야"라고 거절한 것이고, CORS는 서버 답을 브라우저가 버린 것입니다. 콘솔 메시지에 CORS policy가 있는지로 구분합니다.
• *로 열어 두면 해결되지만 그것이 답은 아닙니다. 아무 사이트나 내 API를 호출할 수 있게 됩니다. 개발 중 잠깐이면 몰라도 배포에는 쓰지 않습니다.
• API 키 노출은 별개 문제입니다. 프록시로 우회하면 같이 해결되지만, CORS 자체는 보안 기능이지 키를 숨겨 주는 기능이 아닙니다. 키는 환경변수로 빼 둡니다.