배포 직후 CORS 에러가 터질 때 우선 확인할 로그

CORS 에러는 브라우저 보안 때문에 발생한다. 하지만 브라우저는 자세한 원인을 숨긴다. 실제 요청이 뭔지, 서버가 뭐라고 응답했는지는 개발자 도구 Network 탭과 서버 로그를 함께 봐야 한다.

먼저 예상되는 정상 상태를 정의하기

# 배포된 페이지에서 어떤 domain으로 API를 호출하는가
curl -s https://example.com | grep -o 'https://[a-z0-9.]*' | head -10

API 도메인이 명시된 부분을 찾아서 기록해둔다. 이게 실제 CORS 정책이 적용되는 대상이다.

요청 헤더 확인

// 브라우저 Network 탭에서 보이는 Request headers
Origin: https://example.com
Access-Control-Request-Headers: content-type

Origin이 실제 배포된 도메인과 일치하는가? 로컬에서 localhost:3000으로 테스트하면 배포 환경에서 다를 수 있다.

서버 응답 확인

# 실제 API 요청
curl -i -X OPTIONS https://api.example.com/endpoint \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: GET"

# 응답의 CORS 헤더 확인
# Access-Control-Allow-Origin: https://example.com
# Access-Control-Allow-Methods: GET, POST

서버가 실제로 이 Origin을 허용하도록 설정됐는가?

배포 후 체크리스트

1. HTML head에 실제 API 도메인이 맞게 박혀 있는가
   • 빌드 타임 환경 변수가 올바른가
2. API 서버의 CORS 설정에서 이 도메인을 허용하는가
3. 프로토콜이 같은가 (https vs http)
4. 포트가 같은가 (example.com:3000 vs example.com)

CORS는 결국 "이 출처에서 오는 요청을 나는 받을 거야"라는 약속이다. 한쪽이라도 설정을 빠뜨리면 작동 안 한다.