JavaScript에서 “Blocked by CORS Policy” 오류를 해결하는 방법 (단계별 가이드)

Source: Dev.to

소개

웹 애플리케이션을 만들다가 브라우저 콘솔에 다음과 같은 오류가 표시된다면:

Access to fetch at 'https://api.example.com' from origin 'http://localhost:3000' 
has been blocked by CORS policy.

이는 JavaScript와 API를 다룰 때 초보자들이 가장 흔히 마주치는 문제 중 하나이다.

이 글에서 배울 내용:

• CORS가 무엇인지
• 왜 이 오류가 발생하는지
• Node.js (Express)에서 해결하는 방법
• PHP에서 해결하는 방법
• 프로덕션 환경을 위한 모범 사례

CORS란?

CORS (Cross‑Origin Resource Sharing)는 브라우저 보안 기능이다. 요청이 cross‑origin으로 간주되는 경우는 다음과 같다:

• 프론트엔드가 http://localhost:3000에서 실행될 때
• 백엔드가 https://api.example.com에서 실행될 때

이 두 오리진이 다르기 때문에, 서버가 명시적으로 허용하지 않으면 브라우저가 요청을 차단한다.

Important: CORS는 서버가 아니라 브라우저에 의해 강제된다.

왜 CORS 오류가 발생하는가

CORS 오류는 백엔드 서버가 올바른 HTTP 헤더를 보내지 않을 때 발생한다. 브라우저는 다음과 같은 헤더를 확인한다:

Access-Control-Allow-Origin

해당 헤더가 없으면 브라우저는 요청을 차단한다. 즉, 프론트엔드만으로는 CORS를 해결할 수 없으며 백엔드에서 설정해야 한다.

해결 방법 1: Node.js (Express)에서 CORS 수정

1. CORS 미들웨어를 설치한다:

npm install cors

2. Express 서버를 업데이트한다:

const express = require('express');
const cors = require('cors');

const app = express();

app.use(cors());

app.get('/api/data', (req, res) => {
  res.json({ message: "CORS is fixed!" });
});

app.listen(5000, () => console.log("Server running on port 5000"));

3. 서버를 재시작하고 요청을 다시 테스트한다.

해결 방법 2: PHP에서 CORS 수정

PHP 파일 상단에 다음 헤더를 추가한다:

이렇게 하면 cross‑origin 요청이 허용된다.

중요: 프로덕션에서는 “*” 사용 금지

다음과 같이 사용하면:

header("Access-Control-Allow-Origin: *");

모든 도메인에서 요청을 허용하게 되며, 프로덕션 환경에서는 안전하지 않다. 대신 허용할 도메인을 명시한다:

header("Access-Control-Allow-Origin: https://yourdomain.com");

Postman은 동작하지만 브라우저는 실패하는 이유

• Postman은 동작한다: CORS 제한을 적용하지 않기 때문이다.
• 브라우저는 실패한다: 보안 규칙으로 CORS를 강제하기 때문이다.

빠른 디버그 체크리스트

• 백엔드에 CORS 헤더가 설정되어 있는지 확인한다.
• 변경 후 서버를 재시작한다.
• 브라우저 캐시를 비운다.
• 업데이트된 메시지가 있는지 브라우저 콘솔을 확인한다.

결론

“Blocked by CORS Policy” 오류는 JavaScript 버그가 아니라 브라우저 보안 규칙이다. CORS는 백엔드에서 설정해야 한다는 점을 이해하면 해결 방법은 매우 직관적이다.