Next.js App Router: Route Handler CORS 에러 해결 및 OPTIONS 프리플라이트 응답 헤더 설정가이드

Next.js Route Handler CORS 에러 해결 및 API 응답 헤더 설정 가이드
3초 요약: 이렇게 고치세요
  • 원인: Route Handler가 Access-Control-Allow-Origin 헤더 없이 응답하면, 브라우저가 다른 출처에서 온 요청이라 판단해 응답을 강제로 막음
  • 해결: 라우터 개별 응답에 CORS 헤더 직접 세팅 + OPTIONS 프리플라이트 대응 / 엔드포인트가 많으면 middleware.ts로 일괄 적용
  • 주의: 프론트엔드와 백엔드를 서로 다른 도메인·포트로 분리 배포했을 때 이 에러를 가장 흔하게 마주침
headers: { 'Access-Control-Allow-Origin': 'https://my-app-client.com' }
↓ 왜 이런 에러가 나는지 원리 보기

Next.js Route Handler로 외부 도메인에 API를 열어주려 하면 브라우저 콘솔에 CORS 에러가 뜨는 경우가 많습니다. 로컬에서는 문제없이 통신되던 요청이 배포 도메인에서는 막히는 이유는 브라우저의 동일 출처 정책 때문입니다. 원인과 대응 코드 두 가지를 정리합니다.

Route Handler에서 CORS 에러가 발생하는 원인

CORS(Cross-Origin Resource Sharing: 교차 출처 리소스 공유)는 브라우저가 사용자 보안을 지키기 위해 구현한 동일 출처 정책(SOP)에서 비롯됩니다. 기본적으로 Next.js Route Handler(app/api/route.ts)는 외부 클라이언트가 요청을 보낼 때, 응답 헤더에 "이 외부 도메인의 요청을 허가한다"는 승인 표식을 남겨서 보내주어야 합니다. 이 표식이 바로 Access-Control-Allow-Origin 헤더입니다. Next.js 서버에서 이 헤더를 명시해 주지 않은 채 데이터를 응답하면, 브라우저는 해킹의 위험이 있다고 간주하여 데이터를 강제로 누락시키고 CORS 에러를 발생시킵니다. 프론트엔드와 백엔드를 서로 다른 도메인이나 포트로 분리 배포했을 때 이 에러를 가장 흔하게 마주치게 됩니다.

CORS 보안 필터링 통과 규칙

차단되는 상황 외부 도메인이 Next.js API 호출 -> Next.js 응답 헤더에 허용 표식 누락 -> 브라우저가 수신 거부 및 CORS 차단.
통과되는 상황 CORS 전용 응답 헤더 탑재 -> 브라우저가 허용 도메인 매칭 확인 -> 리소스 정상 수신 성공.

Route Handler에서 CORS 문제를 해결하는 2가지 솔루션

방법 A: Route Handler 개별 응답 헤더 세팅

특정 API 라우터(app/api/data/route.ts) 내부에서 들어오는 요청에 대해 승인 헤더를 수동으로 적용하여 응답하는 방법입니다. 

import { NextResponse } from 'next/server';

export async function GET() {
  const data = { message: "안전한 데이터입니다." };

  return NextResponse.json(data, {
    headers: {
      // 1. 특정 외부 클라이언트 주소 허용 (모든 도메인 허용 시 '*' 입력 가능)
      'Access-Control-Allow-Origin': 'https://my-app-client.com',

      // 2. 허용할 HTTP 메소드 나열
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',

      // 3. 브라우저가 커스텀 헤더를 전송할 수 있게 승인
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}

// 브라우저가 본 요청을 보내기 전 미리 안전한지 검사하는 OPTIONS 요청(Preflight)에 대응
export async function OPTIONS() {
  return new NextResponse(null, {
    status: 204, // No Content
    headers: {
      'Access-Control-Allow-Origin': 'https://my-app-client.com',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}

외부 파트너사에 API를 열어주는 작업에서 GET 응답에만 CORS 헤더를 넣고 OPTIONS 핸들러를 깜빡한 적이 있습니다. 브라우저 콘솔에는 여전히 CORS 에러가 떠서 헤더 설정이 잘못된 줄 알고 한참 값을 바꿔봤는데, 알고 보니 프리플라이트 요청 자체가 별도 핸들러 없이는 204조차 못 받고 막히고 있었습니다.

방법 B: Next.js 미들웨어(middleware.ts)로 글로벌 CORS 세팅

API 엔드포인트가 수십 개가 넘어 매번 소스코드 헤더를 수동 지정하기 어렵다면, 모든 API 통로의 최전방에 위치하는 미들웨어 파일 하나로 일괄 처리하는 것이 좋습니다.

[루트 경로 생성: middleware.ts]

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const response = NextResponse.next();

  // 모든 API (/api/:path*) 요청에 대해 CORS 응답 헤더 일괄 주입
  response.headers.set('Access-Control-Allow-Origin', '*');
  response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
  response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');

  return response;
}

// 미들웨어가 감시할 경로 매칭 패턴 설정
export const config = {
  matcher: '/api/:path*',
};

요약: CORS 정책 대응 핵심 요약 매트릭스

특정 도메인에만 폐쇄적으로 데이터를 제공하고 싶다면 Route Handler마다 개별적으로 headers와 OPTIONS를 정의하는 방식이 보안 측면에서 가장 우수합니다. API 엔드포인트가 많아 중복 코드가 부담스럽다면 middleware.ts에서 CORS 헤더를 일괄 적용하는 편이 관리 효율이 좋습니다.

공식 참고 레퍼런스

웹 표준 CORS 통신 규약과 브라우저 Preflight 정책에 대한 상세 내용은 아래 문서에서 확인할 수 있습니다.

호마다의 웹개발 팁

참고로 Access-Control-Allow-Origin을 '*'로 열어두면 어떤 도메인에서도 요청을 받을 수 있지만, 인증이 필요한 API라면 허용 도메인을 명시적으로 제한하는 편이 안전합니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

TypeScript: Unknown vs Any 타입 차이점과 안전한 타입 가드(Type Guard)

이미지
3초 요약: 이렇게 고치세요 원인: any 는 타입 검사 자체를 포기하는 선언이라, 잘못된 속성 접근이 컴파일 시점엔 통과했다가 런타임에 터짐 해결: 외부 API 응답처럼 타입을 확신할 수 없는 데이터는 unknown 으로 받고, data is T 형태의 타입 가드로 검증한 뒤에만 사용 주의: 타입 가드 내부에서 as Record<string, unknown> 같은 임시 캐스팅으로 속성을 하나씩 검사하는 절차를 생략하면 unknown 을 쓰는 의미가 없어짐 function isUserProfile(data: unknown): data is UserProfile { ... } ↓ 왜 any가 위험한지 원리 보기 실무에서 대규모 TypeScript 프로젝트를 마이그레이션하거나, 외부 API 또는 레거시 라이브러리를 통합하다 보면 필연적으로 "타입을 확신할 수 없는 데이터"를 다루게 됩니다. 이때 많은 개발자들이 급한 마음에 가장 손쉬운 탈출구인 any 를 사용하곤 합니다. 하지만 이는 TypeScript의 가장 큰 무기인 타입 안정성을 스스로 내려놓는 행위이자, 미래의 나에게 런타임 에러라는 시한폭탄을 던지는 것과 같습니다. any 가 왜 위험한지, TypeScript 3.0에서 도입된 unknown 이 이를 어떻게 막아주는지, 그리고 실무에서 바로 써먹을 수 있는 사용자 정의 타입 가드(User-Defined Type Guards) 작성 패턴을 정리합니다. any의 위험성과 unknown의 등장 프로덕션 환경에서 발생한 실제 에러 로그를 분석해 보면, 꽤 많은 비율이 TypeError: Cannot read properties of undefined 에서 시작합니다. 그리고 그 이면에는 높은 확률로 any 타입이 자리 잡고 있죠. any: 타입...
자세한 내용 보기

Next.js 하이드레이션 오류 원인과 해결법 완벽 정리

이미지
3초 요약: 이렇게 고치세요 원인: 서버가 렌더링한 초기 HTML과 브라우저가 처음 그린 HTML 구조가 서로 달라서 발생 — React는 둘이 같을 거라 믿고 결합을 시도하다가 실패함 해결: 잘못된 태그 중첩이면 마크업 수정 / window · localStorage 참조면 useEffect 로 이동 / 시간·랜덤값처럼 매번 달라지는 값이면 ssr: false 로 분리 주의: suppressHydrationWarning 은 경고를 숨길 뿐 원인을 고치는 게 아니라서, 불가피한 텍스트 불일치(타임스탬프 등)에만 제한적으로 써야 함 const [isMounted, setIsMounted] = useState(false); useEffect(() => setIsMounted(true), []); if (!isMounted) return null; // 서버와 첫 클라이언트 렌더는 항상 동일하게 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js를 쓰다 보면 콘솔에 "Hydration failed because the initial UI does not match..."라는 붉은 에러가 뜰 때가 있습니다. 빌드는 멀쩡히 끝났는데 화면이 그려진 직후에 갑자기 나는 에러라서 처음 보면 당황스럽습니다. 원인은 대부분 서버와 클라이언트가 그린 첫 화면이 미묘하게 다르기 때문이고, 패턴이 정해져 있어서 하나씩 짚어보면 금방 잡힙니다. 하이드레이션(Hydration), 정확히 어떤 과정인가 Next.js의 핵심 기능은 서버 사이드 렌더링(SSR)입니다. 서버는 먼저 사용자에게 정적인 HTML 뼈대를 빠르게 그려서 브라우저에 내려보내 줍니다. 그 후, 브라우저(클라이언트)가 이 정적인 HTML 위에 React의 자바스크립트 코드와 이벤트 리스너를 결합하여 ...
자세한 내용 보기

Next.js App Router에서 getServerSideProps 대체 및 데이터 페칭법

이미지
3초 요약: 이렇게 고치세요 원인: App Router는 서버 컴포넌트에서 직접 async/await를 쓸 수 있어 getServerSideProps / getStaticProps 가 아예 없어짐 해결: 빌드 시 캐싱(SSG) → 기본 fetch / 매 요청 최신화(SSR) → { cache: 'no-store' } / 주기 갱신(ISR) → { next: { revalidate: N } } 주의: getServerSideProps 안에 있던 인증 체크 로직은 이제 컴포넌트 함수 내부나 미들웨어로 옮겨야 함 const res = await fetch(url, { cache: 'no-store' }); // SSR과 동일하게 매번 재요청 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js 13 이상에서 App Router가 표준이 되면서, Pages Router에서 쓰던 getServerSideProps 와 getStaticProps 가 더 이상 동작하지 않습니다. 두 함수가 사라진 설계적 이유와, 이를 대체하는 데이터 패칭 방식을 정리했습니다. 왜 getServerSideProps와 getStaticProps가 사라졌을까 과거 Next.js는 페이지 컴포넌트 내부에서만 특정 정적 함수( getServerSideProps 등)를 실행하여 데이터를 미리 받아온 뒤, 이를 컴포넌트의 props 로 넘겨주는 복잡한 직렬화 구조를 가졌습니다. 이로 인해 컴포넌트 간 깊이가 깊어지면 'Props Drilling(프로퍼티 대물림)'이 심해져 코드 관리가 몹시 까다로웠습니다. App Router 환경에서는 서버 컴포넌트(Server Component)가 표준이 됨에 따라 컴포넌트 내에서 직접 비동기 함수(async/await)를 작성할 수 있게 되었습...
자세한 내용 보기