웹 운영
프론트엔드 티켓 작성 전 CORS 오류 체크리스트
CORS 오류를 프론트엔드 버그로 공유하기 전에 preflight, origin, credentials, 헤더, 재현 증거를 정리하는 실무 체크리스트입니다.
검색 의도: 브라우저에는 CORS라고 뜨지만 담당 영역이 애매할 때
CORS 오류는 메시지만 보면 프론트엔드가 고장난 것처럼 보이지만 실제 수정 지점은 API 게이트웨이, 백엔드 응답 헤더, CDN 규칙, 로그인 쿠키 정책, 환경별 origin 허용 목록일 수 있습니다. 콘솔의 빨간 줄만으로는 다음 담당자가 판단하기 어렵습니다. preflight 요청이 있었는지, 어떤 Origin이 갔는지, 서버가 허용 헤더를 돌려줬는지, credentials나 커스텀 헤더 때문에 흐름이 달라졌는지부터 분리해야 합니다.
프론트엔드 티켓을 만들기 전에는 CORS 메시지를 정리해야 할 브라우저 증거로 봅니다. 페이지 URL, API 경로, method, origin, status, 콘솔 문구를 남깁니다. 응답 본문이 JSON이면 https://tools.sambro.space/ko/tools/json-formatter 에서 보기 좋게 만든 뒤 민감값을 지우고, 실패 URL에 인코딩된 파라미터가 있으면 https://tools.sambro.space/ko/tools 로 모양을 확인합니다. 목적은 브라우저가 API 응답을 읽기 전에 막혔는지, 아니면 실제 API 오류가 CORS처럼 보였는지를 구분하는 것입니다.
preflight 실패와 실제 요청 실패를 나누기
첫 번째 확인은 실패한 요청이 OPTIONS preflight인지, 실제 GET, POST, PUT, DELETE 요청인지 보는 것입니다. preflight는 브라우저가 단순하지 않은 method, 커스텀 헤더, credentials, content type에 대해 먼저 허가를 구할 때 나타납니다. OPTIONS에서 막히면 애플리케이션의 실제 API 핸들러까지 도달하지 못했을 수 있습니다. 티켓에 POST 실패라고만 적으면 담당자는 엉뚱한 로그부터 뒤지게 됩니다.
둘 다 있다면 preflight status와 실제 요청 status를 각각 적습니다. 서버 로그에 preflight가 없다면 그 사실도 중요합니다. 프록시, CDN, DNS, mixed content, 로컬 브라우저 정책에서 막혔을 수 있기 때문입니다. preflight는 204인데 실제 요청이 401이라면 기본 CORS 설정보다 인증이나 권한 문제로 범위를 옮겨야 합니다.
origin, credentials, 허용 헤더를 함께 보기
CORS 설정은 조합으로 실패합니다. Access-Control-Allow-Origin이 와일드카드면 넓게 허용하는 것처럼 보이지만 credentials 요청과 함께 쓸 수 없습니다. 쿠키 기반 대시보드는 정확한 origin, credentials 허용, SameSite와 secure 쿠키 설정이 맞아야 합니다. 토큰 기반 요청은 Authorization, X-Tenant-Id 같은 커스텀 헤더가 허용 목록에 없어 실패할 수 있습니다.
티켓에 실제 쿠키, bearer token, 내부 tenant ID를 붙여 넣으면 안 됩니다. 대신 origin host, credentials 포함 여부, 커스텀 헤더 이름, 값이 있었는지 비어 있었는지를 남깁니다. localhost에서 preview 도메인으로 바뀌었다면 이전 origin과 새 origin을 같이 적습니다. 많은 CORS 오류는 코드 회귀가 아니라 새 staging URL, 커스텀 도메인, 배포 preview가 생기면서 허용 목록이 따라가지 못한 문제입니다.
CORS 티켓에서 자주 하는 실수
가장 흔한 실수는 콘솔 문구만 보고하는 것입니다. 콘솔은 유용하지만 method, status, 응답 헤더, 시간 정보를 숨깁니다. 두 번째 실수는 Postman이나 curl에서 성공했으니 API는 정상이라고 판단하는 것입니다. 이런 도구는 브라우저 CORS 규칙을 같은 방식으로 적용하지 않습니다. curl 성공은 엔드포인트가 응답할 수 있다는 뜻이지, 해당 origin의 브라우저가 응답을 읽을 수 있다는 뜻은 아닙니다.
세 번째 실수는 증거를 저장하기 전에 프론트엔드 요청을 바꿔 증상을 우회하는 것입니다. 헤더를 빼거나 credentials를 끄거나 엔드포인트를 바꾸면 오류는 사라질 수 있지만 제품 동작도 바뀝니다. 원래 실패를 먼저 캡처한 뒤 private window, hard refresh, production 동일 사용자, staging 동일 경로, 커스텀 헤더 제거, 안전한 경우 credentials 제거처럼 한 번에 하나씩만 비교합니다.
실무용 CORS 전달 체크리스트
마지막 체크리스트는 고정해 둡니다. 페이지 URL, API URL, method, 브라우저, 환경, 정확한 origin, credentials 포함 여부, preflight status, 실제 요청 status, 관련 응답 헤더, 커스텀 요청 헤더 이름, 타임존이 있는 timestamp, request ID, 최근 도메인이나 proxy 변경, 기대 결과와 실제 결과 한 문장입니다. 스크린샷이 필요하면 계정 정보를 잘라내고 민감값을 지웁니다. 설명이 길어지면 https://tools.sambro.space/ko/tools/word-counter 로 반복 증거를 줄이되 origin과 헤더 정보는 남깁니다.
Sambro 도구만으로도 CORS 오류 주변 정리는 충분히 할 수 있습니다. JSON 응답은 JSON 포맷터로, 복사한 endpoint는 URL 인코더로, 긴 전달 문구는 글자수 세기로 정리합니다. 도구 모음은 https://tools.sambro.space/ko/tools 에 있고 회사 맥락은 https://sambro.space/ 에서 확인할 수 있습니다. 좋은 CORS 티켓은 정책을 대신 고치지는 않지만 담당 지점을 분명히 만듭니다. 프론트엔드 요청 형태, 백엔드 CORS 응답, gateway나 CDN 규칙, 인증 쿠키, 환경 허용 목록 중 어디를 봐야 하는지 빠르게 좁혀 줍니다.