CORS 에러가 반복돼서, 브라우저가 뭘 검사하는지 시뮬레이터로 만들었어요
"Postman에선 되는데 브라우저에선 안 돼요"
개발하다 보면 한 번쯤은 만나는 문구예요. API 서버는 분명 살아있고, curl로 치면 응답이 오는데, 프론트에서 fetch만 하면 빨간 글씨가 뜨죠.
Access to fetch at 'https://api.example.com/data' from origin
'http://localhost:3000' has been blocked by CORS policy
문제는 이 에러가 "서버가 거절했다"가 아니라 브라우저가 응답을 막았다는 뜻이라는 거예요. 서버는 응답을 보냈어요. 응답이 브라우저의 CORS 정책 검사를 통과 못 해서 JS 코드가 못 읽게 된 거죠. 이걸 매번 검색해서 찾기 지겨워서, 브라우저가 실제로 어떤 순서로 검사하는지를 단계별로 보여주는 시뮬레이터를 만들었어요.

만든 도구가 하는 일
요청 쪽(출처, 메서드, Content-Type, 커스텀 헤더, credentials)과 응답 쪽(Access-Control-Allow-* 헤더들)을 따로 설정하게 했어요. 값을 바꾸면 아래 타임라인이 실시간으로 다시 계산돼요.
- 단순 요청 판정: GET/POST/HEAD + 단순 헤더만 + 단순 Content-Type이면 OPTIONS를 안 보내고 바로 본 요청으로 가요
- 프리플라이트: 조건을 벗어나면 브라우저가 먼저
OPTIONS로 "해도 되나요?" 물어봐요 — 실제 헤더 스니펫(Access-Control-Request-Method등)을 그대로 보여줘요 - 응답 검사: 서버의 ACAO/메서드/헤더 허용 목록을 하나씩 비교하고, 막히면 그 단계가 빨간색으로 찍혀요
- 크롬 에러 재현: 최종적으로 차단되면 실제 개발자도구에 뜨는 문구를 그대로 만들어서 콘솔 패널에 보여줘요

삽질 1 — "단순 요청"의 경계가 생각보다 좁았어요
시뮬레이션 로직을 짜면서 제일 헷갈렸던 게 단순 요청(simple request) 판정이에요. 대충 "GET/POST면 프리플라이트 없음"으로 아는 경우가 많은데, 실제론 세 조건을 전부 만족해야 해요.
- 메서드가 GET, HEAD, POST 중 하나
- 헤더가 안전 목록(Accept, Accept-Language, Content-Language, Content-Type) 안에 있음
- Content-Type이
application/x-www-form-urlencoded,multipart/form-data,text/plain중 하나
여기서 함정이 3번이에요. Content-Type: application/json만 붙여도 단순 요청이 아니게 돼요. 그래서 "JSON POST면 무조건 프리플라이트"가 되는 거예요. 요즘 API가 거의 다 JSON이라, 사실상 POST는 대부분 OPTIONS를 거친다고 봐도 돼요.
커스텀 헤더도 마찬가지예요. X-Auth-Token 하나만 붙여도 프리플라이트 대상이에요. 시뮬레이터에서도 헤더 칩 하나 토글하면 타임라인에 OPTIONS 단계가 생겼다 없어졌다 하는 걸 눈으로 볼 수 있게 했어요.
삽질 2 — 와일드카드와 credentials는 같이 못 써요
제일 유명한 함정인데, 만들면서도 다시 확인하게 된 조합이에요.
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true ← 이 조합은 무효!
withCredentials(쿠키, 인증 헤더 포함)를 켜면 브라우저는 ACAO가 *인 응답을 통째로 거부해요. 보안상 당연한 얘기인데, "모든 출처에 쿠키 세션을 열어준다"는 게 말이 안 되니까요. 이때는 요청 Origin을 그대로 echo 해줘야 해요.
그래서 시뮬레이터에도 이 조합을 그대로 재현했어요. credentials를 켠 상태에서 ACAO를 *로 두면 "credentials 사용 시 와일드카드 불가" 에러가 떠요. 시나리오 프리셋에도 이 케이스를 따로 넣어뒀어요.

삽질 3 — Access-Control-Allow-Headers 입력이 번거로웠어요
만들고 나서 스스로 써보다 불편했던 부분이에요. 처음엔 Access-Control-Allow-Headers를 자유 입력칸으로만 뒀거든요. "헤더 이름은 서버마다 제각각이라 칩으로 못 만든다"는 이유였는데, 막상 쓰니까 매번 x-auth-token 치기가 귀찮았어요.
그래서 두 종류의 토글 칩을 추가했어요.
- 지금 요청이 실제 필요로 하는 헤더: 입력한 커스텀 헤더명이 자동으로 칩이 돼요.
X-Foo로 바꾸면 칩도x-foo로 따라와요 - 자주 쓰는 값:
authorization,*같은 대표값
칩 하나 누르면 차단이 풀리는 걸 바로 실험할 수 있게 됐어요. "서버에서 뭘 열어줘야 하는지"를 반대로 읽는 셈이죠.
Postman에서 되는 이유를 다시 정리하면
시뮬레이터를 만들고 나서야 확실히 정리가 됐어요. CORS는 서버의 정책이 아니라 브라우저의 정책이에요. Postman이나 curl은 브라우저가 아니니까 ACAO 검사를 아예 안 해요. 그래서 "Postman은 되는데 브라우저는 안 된다"가 성립하는 거고, 해결 방법도 서버의 응답 헤더를 맞춰주는 것밖에 없어요.
정리하면
CORS 에러를 만나면 이제 순서가 있어요.
- 프리플라이트가 가는 요청인지 확인 (메서드? 커스텀 헤더? JSON Content-Type?)
- OPTIONS 응답에 ACAO/메서드/헤더 허용이 빠짐없이 있는지 확인
- credentials를 쓰면 ACAO에
*금지 +Access-Control-Allow-Credentials: true필수
이 순서를 손으로 몇 번 돌려보면 이후엔 에러 문구만 봐도 어느 단계에서 막힌 건지 감이 와요. 직접 값을 바꿔가며 단계가 끊기는 지점을 보고 싶으면 CORS 시뮬레이터에서 시나리오를 돌려볼 수 있어요. "헤더 미허용"이나 "credentials 함정" 같은 프리셋이 실제 겪는 케이스랑 거의 같아서, 막힌 원인 찾기가 훨씬 빨라져요.
'IT > javaScript' 카테고리의 다른 글
| float 비주얼라이저를 만들다가 부동소수점에 또 당한 이야기 (0) | 2026.11.21 |
|---|---|
| 카메라 게임이 버벅여서 AI 추론을 웹 워커로 옮겼더니 생긴 일 (0) | 2026.11.20 |
| 설치 없이 브라우저만 되는 AI 기능들 — 음성인식·표정분석·음정측정 실전 정리 (0) | 2026.11.15 |
| 브라우저 내장 AI 지도 — Gemini Nano, 지금 뭘 쓸 수 있나 (0) | 2026.11.15 |
| 브라우저 내장 AI가 워커에서 멈춘 이유 — Gemini Nano 실전 연동기 (0) | 2026.11.14 |