안녕하세요, 여러분. 15년 차 풀스택 개발자이자 기술서 작가로서, 오늘도 여러분과 함께 웹 개발의 거친 파도를 헤쳐나가 보려 합니다. 아마 이 글을 클릭하신 분이라면, 지금 당장 브라우저 개발자 도구 콘솔 창에 뜬 새빨간 에러 메시지 때문에 머리를 감싸 쥐고 계실 확률이 99.9%일 겁니다. 바로 그 악명 높은, 개발자라면 누구나 한 번쯤 거쳐 가는 통과의례인 'CORS(Cross-Origin Resource Sharing)' 에러 말이죠.
솔직히 고백하자면, 저도 신입 시절 이 CORS 문제 때문에 장장 3일 밤을 새운 적이 있습니다. "아니, 내 컴퓨터에서 내 서버로 요청을 보내는데 왜 브라우저가 막는 거야?"라며 모니터에 대고 고함을 치기도 했죠. 포스트맨(Postman)이나 cURL로는 너무나 잘 받아와지는 데이터가, 왜 브라우저에서만 실행하면 차단되는지 도무지 이해할 수 없었습니다. 심지어 프로젝트 마감 하루 전에 이 문제가 터져서, 팀원 전체가 패닉에 빠져 멘탈이 붕괴되었던 아찔한 기억도 납니다. 그때 마신 커피만 아마 10잔은 넘었을 거예요. ☕
하지만 너무 걱정하지 마세요. CORS는 개발자를 괴롭히기 위해 만든 '버그'가 아니라, 우리 사용자의 데이터를 보호하기 위해 만든 정교한 '안전장치'입니다. 원리를 알고 나면 두려움은 사라지고, 오히려 든든한 방패처럼 느껴질 겁니다. 오늘은 단순히 "이 코드 복사해서 붙여넣으세요" 식의 얕은 해결책이 아닙니다. CORS가 왜 발생하는지 그 근본적인 원리부터 시작해, 프록시(Proxy) 서버를 활용한 우회법, 백엔드 헤더 설정, 그리고 실무 15년 차 개발자만 알 수 있는 고급 트러블슈팅 팁까지 총망라하여 아주 상세하게 파헤쳐 보겠습니다. 자, 준비되셨나요?
1. CORS, 도대체 넌 누구냐? (원리와 보안 배경)
CORS 문제를 근본적으로 해결하려면 먼저 범인이 누구인지, 그리고 왜 이런 행동을 하는지 명확히 알아야 합니다. 많은 주니어 개발자분이 CORS를 '에러'라고 부르지만, 사실 CORS는 에러가 아니라 브라우저가 제공하는 핵심적인 '보안 기능'입니다. 정확히 말하면, 브라우저는 기본적으로 '동일 출처 정책(SOP, Same-Origin Policy)'이라는 매우 엄격한 규칙을 따르고 있습니다.
동일 출처 정책(SOP)이란 무엇인가?
SOP는 말 그대로 "같은 출처(Origin)에서만 리소스를 공유할 수 있다"는 철칙입니다. 여기서 '출처'란 프로토콜(Protocol, 예: http, https), 호스트(Host, 예: naver.com), 포트(Port, 예: 80, 8080) 이 세 가지가 토씨 하나 틀리지 않고 모두 일치하는 경우를 말합니다. 만약 이 중 하나라도 다르면 브라우저는 "어? 낯선 곳이네? 위험해!"라고 판단하고 데이터 접근을 차단해 버립니다.
예를 들어보겠습니다. 여러분이 `http://localhost:3000`에서 리액트(React) 앱을 띄우고, `http://localhost:8080`에 있는 스프링 부트(Spring Boot) 서버로 데이터를 요청한다고 가정해 봅시다. 우리 눈에는 같은 '내 컴퓨터(localhost)'라서 안전해 보이지만, 브라우저 입장에서는 포트 번호(3000 vs 8080)가 다르므로 엄연히 '다른 출처'입니다. 그래서 가차 없이 차단하는 것이죠. 통계적으로 웹 개발 입문자의 약 70%가 이 로컬 개발 환경 세팅 과정에서 첫 좌절을 맛본다고 합니다.
쉬운 비유를 들어보겠습니다. 여러분이 아파트 A동 101호에 살고 있다고 칩시다. 여러분 집 냉장고를 여는 건 아무 문제가 없죠(Same Origin). 그런데 갑자기 옆 동 B동 202호에 가서 다짜고짜 냉장고 문을 열려고 한다면요? 당연히 문이 잠겨 있어야 정상입니다. 만약 아무나 남의 집 냉장고를 열 수 있다면 도둑이 들끓겠죠. SOP는 바로 이 '잠금장치'입니다. 그리고 CORS는 "B동 202호 주인이 A동 101호 사람에게만 특별히 냉장고 사용을 허락해 주는 출입증"과 같습니다. 즉, 우리는 에러를 고치는 게 아니라, 정당한 출입증을 발급받는 과정을 수행해야 하는 것입니다.
Preflight 요청: 브라우저의 신중한 탐색
개발자 도구의 네트워크(Network) 탭을 유심히 보신 분들은 가끔 내가 보내지도 않은 `OPTIONS`라는 메서드의 요청이 먼저 날아가는 것을 본 적이 있을 겁니다. 이것이 바로 'Preflight(예비) 요청'입니다. 브라우저는 안전을 최우선으로 하기 때문에, 데이터를 변경할 수 있는 본 요청(POST, PUT, DELETE 등)을 보내기 전에 "혹시 저쪽 서버가 나를 받아줄까?" 하고 먼저 간을 봅니다.
마치 소개팅 주선자가 상대방에게 "이 사람 연락처 줘도 될까?"라고 먼저 물어보는 것과 같습니다. 이때 서버가 "응, 괜찮아(200 OK)"라고 응답하면서 `Access-Control-Allow-Origin` 헤더에 허용된 도메인을 담아 보내주면, 그제야 브라우저는 안심하고 진짜 요청을 보냅니다. 반대로 서버가 침묵하거나 거절하면? 브라우저는 즉시 CORS 에러를 뱉으며 본 요청을 아예 시도조차 하지 않습니다. 이 메커니즘을 이해해야 트러블슈팅이 쉬워집니다. 많은 분이 본 요청이 실패했다고 생각하지만, 실제로는 예비 요청 단계에서 문전박대를 당한 경우가 태반이기 때문입니다.
💡 핵심 요약: CORS 에러는 서버가 응답을 안 해서 생기는 게 아닙니다. 서버는 응답을 줬지만, 그 응답에 "너 써도 돼"라는 허가증(헤더)이 없어서 브라우저가 그 데이터를 여러분의 자바스크립트 코드에 넘겨주지 않고 가로채서 버린 것입니다. 범인은 서버도 아니고 클라이언트 코드도 아닌, 그 사이에 있는 '브라우저 정책'입니다.
2. 해결책 1: 서버 사이드 헤더 설정 (정석적인 방법)
가장 정석적이고 근본적인 해결책은 서버에서 "그래, 너는 들어와도 돼"라고 명시적으로 허락해 주는 것입니다. 백엔드 코드를 수정할 권한이 있다면 이 방법이 가장 깔끔합니다. 주로 `Access-Control-Allow-Origin` 헤더를 세팅하는 방식으로 이루어집니다.
Access-Control-Allow-Origin의 마법과 함정
서버는 응답 헤더에 `Access-Control-Allow-Origin`이라는 필드를 포함해야 합니다. 여기에 허용할 클라이언트의 출처(Origin)를 적어주면 됩니다. 예를 들어 `http://localhost:3000`을 적어주면, 브라우저는 이 헤더를 보고 "아, 서버 주인이 3000번 포트에서 온 요청은 받아주라고 했구나"라고 판단하여 데이터를 통과시킵니다.
하지만 실제 프로젝트에서 주니어 개발자들이 가장 자주 저지르는 치명적인 실수가 있습니다. 바로 귀찮다고 해서 와일드카드(`*`)를 사용하여 모든 도메인을 허용해 버리는 것입니다. `Access-Control-Allow-Origin: *` 이렇게 설정하면 개발 단계에서는 편할지 몰라도, 보안상 매우 위험합니다. 마치 집 현관문을 활짝 열어두고 "아무나 들어오세요"라고 써 붙인 것과 같습니다. 인증 정보(Cookie, Token)가 포함된 요청의 경우 브라우저는 와일드카드를 허용하지 않으므로, 결국 구체적인 도메인을 명시해야 하는 시점이 반드시 옵니다.
주요 언어별 설정 예시
1) Node.js (Express)
가장 많이 쓰이는 `cors` 미들웨어를 사용하면 간편합니다.
const cors = require('cors');
const app = express();
<
댓글
댓글 쓰기