Next.js: middleware.ts에서 다중 쿠키 추출 및 조작 에러 해결법

Next.js middleware.ts에서 다중 쿠키 추출 및 조작 에러 해결 가이드
3초 요약: 이렇게 고치세요
  • 원인: 미들웨어 안에서 request.cookies.set()이나 request.headers.set()을 호출해도, 그 변경이 응답이나 다음 라우트로 자동 전파되지 않음
  • 해결: 요청 헤더는 NextResponse.next({ request: { headers } })로, 브라우저에 내려줄 쿠키는 같은 응답의 response.cookies.set()으로 각각 명시적으로 설정
  • 주의: Cookie 헤더를 통째로 덮어쓰면 세션 토큰 외의 다른 쿠키가 전부 사라짐 — 기존 값에 이어붙여야 함
const response = NextResponse.next({ request: { headers: requestHeaders } });
response.cookies.set('session-token', newSessionToken, { httpOnly: true });
↓ 왜 이런 에러가 나는지 원리 보기

Next.js App Router 환경에서 인증 토큰을 서버 미들웨어(middleware.ts) 수준에서 실시간으로 검증하고 갱신하려다, 새로 설정한 쿠키가 브라우저에 구워지지 않거나 다음 페이지에서 감지되지 않는 문제로 골머리를 앓으신 적이 있을 겁니다. 기존 Node.js 서버나 Route Handler를 짜던 감각으로 res.setHeader() 같은 Express식 객체를 찾거나 next/headers의 cookies().set()을 미들웨어에 그대로 쓰면, 애초에 미들웨어 함수에는 res 인자가 없고 cookies().set()도 미들웨어 밖에서만 허용되는 API라 즉시 에러가 나서 바로 알아챌 수 있습니다. 정작 까다로운 건 NextRequest/NextResponse의 올바른 API(request.cookies.set(), request.headers.set())를 그대로 썼는데도 에러 하나 없이 조용히 쿠키가 유실되는 경우입니다.

왜 미들웨어 안에서는 쿠키 조작이 마음대로 되지 않는가?

원인은 Next.js middleware.ts 파일이 기본적으로 실행되어 온 엣지 런타임(Edge Runtime)의 제약과 관련이 있습니다. 일반적인 서버 컴포넌트(page.tsx)나 Route Handler(route.ts)는 Node.js 풀 런타임 위에서 돌기 때문에 Node.js API를 자유롭게 쓸 수 있지만, 미들웨어는 오랫동안 Node.js 기능을 걷어낸 가벼운 V8 엔진 기반 웹 표준 API만 지원해 왔습니다.

버전 참고: Next.js 15.5부터 미들웨어에서 Node.js 런타임 사용이 정식 지원되었고, Next.js 16부터는 파일명이 proxy.ts로 바뀌면서 Node.js 런타임이 기본값이 되었습니다. 최신 버전을 쓰고 있다면 아래에서 설명하는 엣지 런타임 제약이 기본으로 적용되지 않을 수 있으니, 먼저 package.json의 Next.js 버전과 runtime 설정을 확인하세요.

진짜 문제는 미들웨어 안에서 요청 객체를 수정할 수 없다는 게 아니라, 그 수정이 자동으로 전파되지 않는다는 데 있습니다. request.cookies.set()이나 request.headers.set()을 호출하면 그 실행 컨텍스트 안의 요청 객체 자체는 바뀌지만, 이 변경 내용을 NextResponse.next({ request: { headers } }) 형태로 명시적으로 실어 보내지 않으면 이후 실행되는 페이지 컴포넌트나 API 핸들러로 전달되지 않습니다. 마찬가지로 브라우저에 새 쿠키를 내려주려면 반환하는 응답 객체에 response.cookies.set()을 별도로 호출해야 하며, 다운스트림 전달과 브라우저 응답이라는 이 두 경로는 서로 자동으로 동기화되지 않고 각각 명시적으로 연결해 줘야 합니다.

미들웨어 쿠키 흐름 및 유실 단절 메커니즘

요청 쪽만 수정하고 끝내기 request.cookies.set() 호출 -> 미들웨어 실행 컨텍스트 안에서만 존재 -> NextResponse.next()에 실어 보내지 않으면 다음 라우터/브라우저 어디에도 전달되지 않고 폐기됨.
요청과 응답 양쪽에 각각 명시 갱신된 요청 헤더는 NextResponse.next({ request: { headers } })로, 브라우저에 내려줄 쿠키는 같은 응답의 response.cookies.set()으로 각각 설정 -> 페이지 및 브라우저까지 정상 연동.

자주 나타나는 상황: 무정지 토큰 리프레시 미들웨어

만료 시간이 15분인 단기 액세스 토큰이 끝날 때마다, 미들웨어가 갱신 API를 뒤에서 호출해 새 쿠키를 클라이언트에 굽고 요청을 통과시키는 무정지 갱신 로직은 흔히 쓰는 패턴입니다.

예전에 외주로 맡았던 결제 대시보드 프로젝트에서 정확히 이 패턴을 썼다가 곤란해진 적이 있습니다. 분명 미들웨어 안에서 쿠키 재발급 로직을 호출했는데도 브라우저에는 신규 쿠키가 주입되지 않아, 다음 페이지로 넘어갈 때 로그아웃 튕김 현상이 연쇄적으로 터졌습니다. 처음엔 토큰 갱신 API 자체가 실패하는 줄 알고 서버 로그부터 뒤졌는데, API는 매번 정상 응답을 주고 있었습니다. 한참 헤매다가 원인이 NextResponse.next()로 다음 라우터에 흐름을 이어주며 만든 응답 객체에, 브라우저로 되돌아가는 최종 응답의 Set-Cookie를 실어 보내지 않았기 때문이라는 걸 알아챘습니다.

요청 헤더 갱신과 응답 쿠키 설정을 하나의 응답 객체 위에서 함께 처리하도록 정리해두면, 토큰 재갱신 흐름에서 이런 로그아웃 튕김 문제를 막을 수 있습니다.

실전 코드: 미들웨어 다중 쿠키 동기화 및 덮어쓰기

Next.js 미들웨어에서 요청 쿠키와 응답 쿠키의 바인딩 유실을 방지하고 데이터를 동기화시키는 미들웨어 전체 작성 가이드 코드 예시입니다. 

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

export async function middleware(request: NextRequest) {
  // 1. 요청(Request) 객체로부터 쿠키 읽어오기
  const oldSession = request.cookies.get('session-token')?.value;

  // 참고: 실제 서비스에서는 문자열 단순 비교가 아니라 JWT의 exp 클레임을 디코딩하는 등
  // 진짜 만료 여부를 검증해야 합니다. 아래 비교는 예시를 위한 단순화입니다.
  if (oldSession === 'expired-token-value') {
    const newSessionToken = 'refreshed-jwt-secure-token';

    // A단계: 기존 요청 헤더를 복제하고, Cookie 헤더는 기존 값에 이어붙여 갱신
    // (그냥 덮어쓰면 session-token 외의 다른 쿠키들이 전부 사라짐)
    const requestHeaders = new Headers(request.headers);
    const otherCookies = (requestHeaders.get('Cookie') ?? '')
      .split('; ')
      .filter((c) => c && !c.startsWith('session-token='))
      .join('; ');
    requestHeaders.set(
      'Cookie',
      [otherCookies, `session-token=${newSessionToken}`].filter(Boolean).join('; ')
    );

    // B단계: 갱신된 요청 헤더를 실어 응답을 하나만 생성
    // (요청 헤더는 이후 서버 컴포넌트/Route Handler에서, 쿠키는 브라우저에서 각각 읽힘)
    const response = NextResponse.next({
      request: { headers: requestHeaders },
    });

    // C단계: 브라우저에 내려줄 Set-Cookie는 response.cookies로 직접 설정
    // (Set-Cookie 헤더 문자열을 그대로 복사하면 쿠키가 여러 개일 때 유실될 수 있음)
    response.cookies.set({
      name: 'session-token',
      value: newSessionToken,
      path: '/',
      httpOnly: true,
      secure: true,
      sameSite: 'strict',
    });

    return response;
  }

  return NextResponse.next();
}

// 미들웨어 감시 제외 경로 (정적 리소스 필터링)
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api).*)'],
};

해결 코드의 라인별 동작 해설

위 해결 코드의 핵심은 요청 헤더 전파와 응답 쿠키 설정을 서로 다른 API로, 하지만 하나의 응답 객체 안에서 함께 처리하는 것입니다. request.cookies.set()이나 request.headers.set()으로 미들웨어 안의 요청 객체를 고쳐도, 그 변경 사항 자체는 어디에도 자동으로 전달되지 않습니다. NextResponse.next({ request: { headers } })에 명시적으로 실어 넘겨줘야만 이후 실행되는 page.tsx나 Route Handler의 cookies()/headers()에서 이 값을 읽을 수 있습니다.

이때 Cookie 헤더는 기존 값을 통째로 덮어쓰지 않고 이어붙여야 합니다. 그렇지 않으면 세션 토큰 외에 요청에 실려 있던 다른 쿠키(로케일, CSRF 토큰 등)가 전부 사라져 다운스트림 로직이 깨질 수 있습니다. 브라우저로 내려가는 Set-Cookie는 응답 헤더를 문자열로 복사하는 대신 response.cookies.set()을 직접 호출해서 설정합니다. Set-Cookie는 동시에 여러 개가 존재할 수 있는 헤더라, 문자열 하나로 합쳐서 복사하면 쿠키가 두 개 이상일 때 유실될 위험이 있기 때문입니다.

정리하면 미들웨어에서 요청 헤더만 고쳐서는 브라우저에도, 뒤이은 서버 컴포넌트에도 반영되지 않습니다. 응답 헤더까지 함께 동기화해야 양쪽 모두에 안전하게 반영됩니다. 그리고 최신 Next.js를 쓰고 있다면, 애초에 이 글에서 설명한 엣지 런타임 제약 자체가 기본으로 걸리지 않을 수 있다는 점도 함께 확인하시길 권합니다.

추가 추천 자료 및 공식 레퍼런스

Next.js 미들웨어의 쿠키 다중 설정 및 수정 명세, 그리고 Next.js 16의 proxy.ts 전환 안내는 다음 공식 문서에서 확인하실 수 있습니다.

호마다의 웹개발 팁

미들웨어(middleware.ts, Next.js 16부터는 proxy.ts)에서 양방향 쿠키 세팅을 수동으로 맞춰주는 패턴은 세션 인증 제어의 기본기입니다. JWT 같은 인증 방식의 기초부터 정리한 글은 [호마다의 IT 개발 입문 블로그] 에서 확인하실 수 있습니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

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)를 작성할 수 있게 되었습...
자세한 내용 보기