○웹살림
← 모든 기록
브라우저 CORS 오류 원인 확인하고 서버 설정 점검하는 방법 대표 이미지
문제 해결

브라우저 CORS 오류 원인 확인하고 서버 설정 점검하는 방법

브라우저 CORS 오류가 발생할 때 원인을 확인하고 서버 설정을 점검하여 해결하는 실전 가이드입니다.

글

브라우저 CORS 오류가 발생하면 개발자 도구의 콘솔 탭에서 구체적인 오류 메시지를 확인합니다. 확인된 원인에 따라 서버 응답에 Access-Control-Allow-Origin 헤더를 추가하거나 설정을 수정합니다. 필요하면 프록시 서버를 통해 우회할 수도 있습니다.

CORS 오류의 기본 개념과 발생 원인 이해하기

CORS(Cross-Origin Resource Sharing)는 웹 페이지가 다른 출처의 리소스를 요청할 때 브라우저가 시행하는 보안 정책입니다. 출처(Origin)는 프로토콜, 호스트, 포트의 조합으로 동일 출처가 아니면 요청이 차단될 수 있습니다. 이는 CSRF나 XSS 같은 공격을 방지하기 위한 Same-Origin Policy 때문에 필요합니다. CORS는 서버가 특정 헤더를 통해 안전한 교차 출처 요청을 허용하도록 설계되었습니다.

브라우저 콘솔에서 오류 메시지 확인하기

브라우저 개발자 도구의 콘솔 탭(Ctrl+Shift+I 또는 F12)을 열면 CORS 관련 오류가 표시됩니다. “has been blocked by CORS policy”라는 문구와 함께 요청이 차단된 구체적인 이유가 나타납니다. 예를 들어 “No ‘Access-Control-Allow-Origin’ header is present”는 서버 응답에 헤더가 없음을 의미합니다. 오류 메시지를 읽으면 출처 불일치, 허용되지 않은 메서드, 자격 증명 문제 등 원인을 파악할 수 있습니다.

서버 응답 헤더 점검하기 (Access-Control-Allow-Origin 등)

CORS 오류를 해결하려면 서버가 응답에 적절한 CORS 헤더를 포함해야 합니다. 가장 기본적인 것은 Access-Control-Allow-Origin 헤더로, 허용할 출처나 와일드카드(*)를 지정합니다. 자격 증명(쿠키 등)을 포함하는 요청은 Access-Control-Allow-Credentials 헤더도 필요합니다. 또한 미리 허용된 메서드(Access-Control-Allow-Methods)와 헤더(Access-Control-Allow-Headers)를 명시해야 프리플라이트 요청이 정상 처리됩니다.

서버 설정 수정하기 (Apache, Nginx 등)

서버 설정에 따라 CORS 헤더를 추가하는 방법이 다릅니다. 아래 단계를 참고하세요.

  1. Apache 서버: .htaccess 파일이나 가상 호스트 설정에서 Header set Access-Control-Allow-Origin "https://yourdomain.com"을 추가합니다.
  2. Nginx 서버: 서버 블록 안에 add_header Access-Control-Allow-Origin https://yourdomain.com;을 추가합니다.
  3. Express(Node.js): cors 미들웨어를 설치하고 app.use(cors({ origin: 'https://yourdomain.com' }))와 같이 설정합니다.
  4. 기타 서버: 공식 문서를 참고해 적절한 헤더를 응답에 포함합니다.

서버 설정을 변경한 후에는 반드시 변경 사항을 적용하고 브라우저 캐시를 지운 뒤 다시 테스트합니다. SSL 인증서 오류가 함께 발생한다면 SSL 인증서 오류 해결 가이드를 함께 확인하세요. Vercel 환경에서 환경 변수가 올바르지 않다면 Vercel 환경 변수 오류 수정 가이드도 참고할 수 있습니다.

프록시 서버 사용 고려하기

직접 서버 설정이 어렵거나 임시 해결이 필요할 때는 프록시 서버를 활용할 수 있습니다. 프록시는 클라이언트와 대상 서버 사이에서 요청을 중계해 출처를 동일하게 만듭니다. 예를 들어 개발 중에는 http-proxy-middleware나 CRA의 프록시 설정을 사용하거나, 크롬 확장 프로그램을 이용해 CORS를 우회할 수 있습니다. 다만 프록시 방법은 보안에 취약할 수 있으므로 프로덕션 환경에서는 권장하지 않습니다.

참고 자료