작성일 2026년 11월 18일 · 기준: MDN Web Docs CORS 문서, Express cors 미들웨어 문서, OWASP
핵심 답: CORS 오류는 프론트엔드 코드가 틀려서가 아니라, 다른 출처(도메인·프로토콜·포트)의 서버가 “이 출처는 읽어도 돼”라는 응답 헤더를 주지 않아서 브라우저가 응답을 막는 거예요. 정석 해결은 서버가 Access-Control-Allow-Origin에 허용할 출처를 정확히 적어 주는 것이고, 쿠키를 보낸다면 * 대신 정확한 출처와 Access-Control-Allow-Credentials: true가 필요해요.

안녕하세요, 잇커니즘이에요. 프론트엔드에서 API를 호출했는데 콘솔에 blocked by CORS policy가 빨갛게 찍히면, 처음에는 대부분 프론트 코드를 의심해요. 그런데 CORS는 브라우저와 서버 사이의 약속이라 해결의 열쇠는 거의 항상 서버 응답 헤더에 있어요. 이 글은 개발자뿐 아니라 개발자와 같이 일하는 기획자·디자이너도 “지금 무슨 문제인지” 이해할 수 있게, 원인 → 현업에서 쓰는 해결 방식 → 흔한 실수 → 체크리스트 순서로 정리했어요.
CORS 오류는 왜 생기나요?
브라우저에는 동일 출처 정책(Same-Origin Policy)이 있어요. 한 출처에서 불러온 스크립트가 다른 출처의 응답을 마음대로 읽지 못하게 막는 보안 규칙이에요. 여기서 출처(origin)는 프로토콜 + 도메인 + 포트를 묶은 말이에요. 그래서 http://localhost:3000에서 http://localhost:8080을 부르는 것도 포트가 달라 교차 출처예요.
CORS(교차 출처 리소스 공유)는 이 제한을 서버가 원하는 만큼만 풀어 주는 표준이에요. 서버가 응답에 Access-Control-Allow-Origin 같은 헤더를 붙여 “이 출처는 허용”이라고 알려 주면, 브라우저가 그때 응답을 스크립트에 넘겨줘요. 중요한 점은, 오류가 나도 요청 자체는 서버에 도착했을 수 있다는 거예요. 막히는 건 ‘응답을 읽는 단계’예요. 상태 코드가 함께 보인다면 HTTP 상태 코드 정리 글도 같이 보면 원인 좁히기가 쉬워요.
콘솔 메시지로 CORS 원인을 어떻게 찾나요?
MDN 문서에 따르면 보안상 이유로 JavaScript 코드에서는 “CORS 오류가 났다”는 사실만 알 수 있고, 자세한 이유는 브라우저 개발자도구 콘솔에서만 볼 수 있어요. 개발자도구(F12) → 콘솔과 네트워크 탭을 열고 실패한 요청을 다시 재현해 보세요. 자주 보는 메시지는 아래처럼 읽으면 돼요.
| 콘솔 메시지(요지) | 뜻 | 서버에서 할 일 |
| No 'Access-Control-Allow-Origin' header | 허용 헤더가 아예 없음 | 허용할 출처를 헤더에 추가 |
| does not match / 다른 값과 불일치 | 헤더 값이 요청 출처와 다름 | 프로토콜·포트까지 정확히 맞추기 |
| Multiple values / 여러 개 허용 안 됨 | 헤더가 두 번 붙음(서버+프록시 등) | 한 곳에서만 붙이기 |
| Credential is not supported if ... '*' | 쿠키를 보내는데 *로 응답 | 정확한 출처 + Allow-Credentials: true |
| preflight ... did not succeed / not ok | 사전 요청(OPTIONS)이 실패 | OPTIONS에 2xx와 CORS 헤더로 응답 |
| Did not find method / missing token in Allow-Headers | 허용 메서드·헤더 목록에 없음 | Allow-Methods·Allow-Headers에 추가 |
사전 요청(preflight)은 언제 보내나요?
PUT·DELETE 같은 메서드를 쓰거나, Authorization 같은 커스텀 헤더를 붙이거나, Content-Type: application/json으로 보내면 브라우저는 실제 요청 전에 OPTIONS 메서드로 “이렇게 보내도 돼?”를 먼저 물어봐요. 이게 사전 요청(프리플라이트)이에요. 서버가 이 OPTIONS 요청에 허용 헤더를 담아 성공 응답을 줘야 실제 요청이 나가요.

사전 요청 응답에는 보통 이런 헤더가 필요해요. Access-Control-Max-Age는 사전 요청 결과를 몇 초 동안 캐시할지 정하는 값이고, MDN 기준 브라우저마다 최대값이 따로 있어요.
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 600
Vary: Origin
서버에서 CORS는 어떻게 설정하나요?
현업에서는 프레임워크가 제공하는 CORS 설정을 쓰는 게 보통이에요. 예를 들어 Node.js의 Express라면 공식 문서에 나온 cors 미들웨어로 허용 출처를 지정해요. 아래는 예시 코드예요.
// npm install cors
const express = require('express');
const cors = require('cors');
const app = express();
const allowList = ['https://app.example.com', 'http://localhost:3000'];
app.use(cors({
origin(origin, callback) {
// 허용 목록에 있는 출처만 통과
if (!origin || allowList.includes(origin)) return callback(null, true);
callback(new Error('Not allowed by CORS'));
},
credentials: true, // 쿠키를 주고받을 때만
}));
Spring, Django, FastAPI 등 다른 프레임워크도 ‘허용 출처 목록’, ‘허용 메서드·헤더’, ‘자격 증명 허용 여부’ 세 가지를 설정한다는 구조는 같아요. 백엔드가 다른 팀이라면 이 세 가지를 정리해서 요청하면 대화가 빨라져요.
쿠키·로그인 정보를 보낼 때 왜 *를 쓰면 안 되나요?
로그인 쿠키처럼 자격 증명을 함께 보내려면 프론트에서 fetch(url, { credentials: 'include' })를 써야 해요. 이때 MDN 문서대로 서버는 Access-Control-Allow-Origin에 와일드카드 *가 아닌 특정 출처를 적어야 하고, Access-Control-Allow-Credentials: true도 보내야 해요. 요청 출처에 따라 응답 값이 달라지므로 Vary: Origin도 함께 넣어 캐시가 섞이지 않게 해요.

OWASP 보안 가이드는 신뢰하는 도메인만 골라 허용하고, 와일드카드나 요청의 Origin 값을 검사 없이 그대로 돌려주는 방식은 피하라고 권해요. 또 CORS가 CSRF 공격까지 막아 주지는 않으니 서버의 기존 보안 검사는 그대로 유지해야 해요.
개발 환경에서 CORS를 우회하는 방법은?
로컬 개발 중 백엔드 설정을 바로 바꿀 수 없을 때는 개발 서버 프록시를 많이 써요. 프론트 개발 서버(Vite, webpack dev server 등)가 /api 요청을 대신 백엔드로 전달하면, 브라우저 입장에서는 같은 출처로 요청한 셈이라 CORS가 생기지 않아요. CORS는 브라우저가 지키는 규칙이라 서버끼리 주고받는 요청에는 적용되지 않기 때문이에요.
다만 프록시는 개발 편의용이에요. 운영 환경에서는 결국 서버의 CORS 설정이나 같은 도메인 구성으로 풀어야 해요. 브라우저 보안 기능을 끄는 확장 프로그램이나 실행 옵션은 다른 사이트 이용 중에도 위험할 수 있으니 권하지 않아요.
CORS 설정에서 흔한 실수는 무엇인가요?
- 끝 슬래시·포트 불일치:
https://app.example.com/처럼 경로를 붙이거나 포트를 빠뜨리면 일치하지 않아요. 출처에는 경로가 들어가지 않아요. - OPTIONS를 인증 미들웨어가 막음: 사전 요청에는 쿠키나 토큰이 없어서 401이 나기 쉬워요. CORS 처리를 인증보다 앞에 두세요.
- 오류 응답에만 헤더가 빠짐: 500 에러 응답에 CORS 헤더가 없으면 실제 원인 대신 CORS 오류로 보여요.
- 헤더 중복: 앱과 Nginx·API 게이트웨이 양쪽에서 붙이면 ‘여러 값’ 오류가 나요.
- 무조건 *: 공개 API가 아니라면 허용 목록 방식으로 바꾸는 게 안전해요.
CORS 오류 해결 체크리스트
- 콘솔과 네트워크 탭에서 실패한 요청이 실제 요청인지 OPTIONS 사전 요청인지 확인했나요?
- 요청 출처(프로토콜·도메인·포트)와 응답의 Access-Control-Allow-Origin 값이 정확히 같나요?
- 쿠키를 보낸다면 credentials: include, 특정 출처, Allow-Credentials: true 세 가지가 모두 맞나요?
- 커스텀 헤더·메서드가 Allow-Headers·Allow-Methods에 들어 있나요?
- 에러 응답과 OPTIONS 응답에도 CORS 헤더가 붙나요? 헤더가 두 번 붙지는 않나요?
CORS 오류, 자주 묻는 질문
Q. 프론트엔드 코드만 고쳐서 CORS를 해결할 수 있나요?
운영 환경에서는 어려워요. 허용 여부는 서버 응답 헤더로 정해지기 때문이에요. 프론트에서 할 수 있는 건 개발 중 프록시를 쓰거나, 쿠키 전송 옵션(credentials)을 맞추는 정도예요.
Q. Postman에서는 잘 되는데 브라우저에서만 안 돼요.
정상이에요. CORS는 브라우저가 지키는 규칙이라 Postman이나 서버 간 호출에는 적용되지 않아요. 그래서 “API는 잘 된다”와 “브라우저에서 읽을 수 있다”는 별개로 확인해야 해요.
Q. mode: 'no-cors'로 바꾸면 해결되나요?
오류 메시지는 사라질 수 있지만 응답 내용을 읽을 수 없는 ‘불투명 응답’이 와요. API 데이터를 써야 하는 상황에서는 해결책이 아니에요.
Q. 기획자나 디자이너가 알아 두면 좋은 점은?
“CORS 오류”는 대개 서버 설정 작업이 필요하다는 뜻이에요. 새 도메인이나 스테이징 주소를 추가할 때 ‘허용 출처 목록에 이 주소를 넣어야 한다’는 걸 일정에 함께 넣어 두면 배포 직전 혼란을 줄일 수 있어요.
정리
CORS 오류는 “다른 출처의 서버가 읽기를 허락하지 않았다”는 브라우저의 신호예요. 콘솔 메시지로 어떤 헤더가 문제인지 확인하고, 서버에서 허용 출처·메서드·헤더·자격 증명 네 가지를 정확히 맞추면 대부분 해결돼요.
출처
'IT정보' 카테고리의 다른 글
| 윈도우11 시작프로그램 끄기, 설정·작업 관리자로 부팅 속도 높이는 법 (0) | 2026.11.19 |
|---|---|
| 윈도우11 클립보드 기록 보기 Win+V, 고정·삭제·안될 때 해결 (0) | 2026.11.17 |
| HTTP 상태 코드 정리, 401과 403 차이부터 500 에러까지 (0) | 2026.11.16 |
| 안드로이드 오토 연결 안됨 해결 방법, USB·무선 체크리스트 총정리 (0) | 2026.11.15 |
| 윈도우11 캡처 단축키 총정리, 부분 캡처부터 저장 위치까지 (0) | 2026.11.14 |