Spring Boot에서 CORS 오류 완벽 해결하기 – @CrossOrigin, WebMvcConfigurer, 예외 처리까지

Spring Boot에서 CORS 오류 해결하는 가장 쉬운 방법 (@CrossOrigin)

프론트엔드와 백엔드를 따로 개발하다 보면 처음 맞닥뜨리는 문제가 바로 CORS 오류입니다. 이 글에서는 CORS 오류가 왜 발생하는지, 프론트와 백엔드에서 각각 어떻게 확인하고 해결해야 하는지를 간단하고 실용적인 코드와 함께 설명합니다.

✅ CORS 오류란 무엇인가요?

CORS(Cross-Origin Resource Sharing)는 다른 도메인 간에 리소스를 공유할 수 있는지를 브라우저가 판단해 요청을 차단하거나 허용하는 보안 정책입니다.

예: 프론트가 http://localhost:3000이고 백엔드가 http://localhost:8080일 때, 브라우저는 출처가 다르다고 판단해 기본적으로 차단합니다.

🚨 CORS 오류는 언제 발생하나요?

주로 아래 조건에서 발생합니다:

• 프론트와 백엔드의 포트 또는 도메인이 다를 때
• 프론트에서 Authorization, Content-Type 같은 헤더를 포함할 때
• credentials: 'include' 등 인증 관련 옵션을 사용하는 경우

브라우저 오류 예시:

Access to fetch at 'http://localhost:8080/api/data' from origin 'http://localhost:3000' 
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present...

🧪 프론트엔드에서 먼저 확인해야 할 것들

CORS 오류는 백엔드뿐 아니라 프론트엔드 설정이나 요청 방식 때문에 발생할 수 있어요. 다음 항목들을 꼭 확인해보세요:

• 요청 주소가 백엔드 주소와 정확히 일치하는지 (포트 포함)
• 헤더에 Content-Type, Authorization 같은 커스텀 헤더가 포함되어 있는지
• credentials 옵션을 사용하는지 (쿠키, 세션 포함 여부)

// 예시: credentials 포함 시
fetch("http://localhost:8080/api/data", {
  method: "GET",
  credentials: "include" // 쿠키 포함 시 CORS 정책 강화됨
});

* 참고: 이 경우 백엔드에서 allowCredentials(true)와 allowedOrigins를 명확히 설정해야 합니다.

🛠️ Spring Boot에서 CORS 해결 방법

 

@CrossOrigin 사용

@RestController
public class ApiController {

```
@CrossOrigin(origins = "http://localhost:3000")
@GetMapping("/api/data")
public String getData() {
    return "Hello from backend";
}
```

} 

➡️ 빠르게 테스트하거나, 컨트롤러 단위로 적용할 때 간편합니다.

 

WebMvcConfigurer로 전역 설정

@Configuration
public class WebConfig implements WebMvcConfigurer {

```
@Override
public void addCorsMappings(CorsRegistry registry) {
    registry.addMapping("/**")
        .allowedOrigins("http://localhost:3000")
        .allowedMethods("GET", "POST", "PUT", "DELETE")
        .allowCredentials(true);
}
```

} 

➡️ 전체 API에 공통 설정을 적용하고 싶을 때 유용합니다.

⚠️ CORS 설정 시 주의할 점

• allowedOrigins = "*" 과 allowCredentials(true)는 함께 사용할 수 없습니다.
• OPTIONS 프리플라이트 요청을 허용해야 하는 경우도 있습니다.
• 배포 시에는 도메인을 명확하게 지정해야 합니다.

 

🧰 마무리

✔️ 빠른 테스트는 @CrossOrigin
✔️ 프로젝트 전체에는 WebMvcConfigurer
로 CORS를 처리하는 것을 추천합니다.

프론트와 백을 분리한 구조에서는 CORS 오류가 자주 발생하지만, 원리만 이해하면 빠르고 안정적으로 해결할 수 있어요!