함수: NextResponse | Next.js

출처 URL: https://nextjs.org/docs/pages/api-reference/functions/next-response

NextResponse

마지막 업데이트: 2026년 2월 20일

NextResponse는 추가 편의 메서드로 Web Response API를 확장합니다.

`cookies`

응답의 Set-Cookie 헤더를 읽거나 변경합니다.

`set(name, value)`

이름이 주어지면 해당 값으로 쿠키를 응답에 설정합니다.

    // Given incoming request /home
    let response = NextResponse.next()
    // Set a cookie to hide the banner
    response.cookies.set('show-banner', 'false')
    // Response will have a `Set-Cookie:show-banner=false;path=/home` header
    return response

`get(name)`

쿠키 이름이 주어지면 해당 쿠키 값을 반환합니다. 쿠키가 없으면 undefined가 반환됩니다. 쿠키가 여러 개면 첫 번째가 반환됩니다.

    // Given incoming request /home
    let response = NextResponse.next()
    // { name: 'show-banner', value: 'false', Path: '/home' }
    response.cookies.get('show-banner')

`getAll()`

쿠키 이름이 주어지면 해당 쿠키의 모든 값을 반환합니다. 이름이 없으면 응답의 모든 쿠키를 반환합니다.

    // Given incoming request /home
    let response = NextResponse.next()
    // [
    //   { name: 'experiments', value: 'new-pricing-page', Path: '/home' },
    //   { name: 'experiments', value: 'winter-launch', Path: '/home' },
    // ]
    response.cookies.getAll('experiments')
    // Alternatively, get all cookies for the response
    response.cookies.getAll()

`has(name)`

쿠키 이름이 주어지면 응답에 해당 쿠키가 존재할 때 true를 반환합니다.

    // Given incoming request /home
    let response = NextResponse.next()
    // Returns true if cookie exists, false if it does not
    response.cookies.has('experiments')

`delete(name)`

쿠키 이름이 주어지면 응답에서 해당 쿠키를 삭제합니다.

    // Given incoming request /home
    let response = NextResponse.next()
    // Returns true for deleted, false if nothing is deleted
    response.cookies.delete('experiments')

`json()`

주어진 JSON 본문으로 응답을 생성합니다.

app/api/route.ts

JavaScriptTypeScript

    import { NextResponse } from 'next/server'

    export async function GET(request: Request) {
      return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
    }

`redirect()`

URL로 리다이렉트하는 응답을 생성합니다.

    import { NextResponse } from 'next/server'

    return NextResponse.redirect(new URL('/new', request.url))

URL은 NextResponse.redirect() 메서드에서 사용되기 전에 생성하고 수정할 수 있습니다. 예를 들어 request.nextUrl 속성으로 현재 URL을 얻은 뒤 수정하여 다른 URL로 리다이렉트할 수 있습니다.

    import { NextResponse } from 'next/server'

    // Given an incoming request...
    const loginUrl = new URL('/login', request.url)
    // Add ?from=/incoming-url to the /login URL
    loginUrl.searchParams.set('from', request.nextUrl.pathname)
    // And redirect to the new URL
    return NextResponse.redirect(loginUrl)

`rewrite()`

원래 URL을 유지한 채 주어진 URL을 리라이트(프록시)하는 응답을 생성합니다.

    import { NextResponse } from 'next/server'

    // Incoming request: /about, browser shows /about
    // Rewritten request: /proxy, browser shows /about
    return NextResponse.rewrite(new URL('/proxy', request.url))

`next()`

next() 메서드는 프록시에서 유용하며, 일찍 반환하고 라우팅을 계속할 수 있습니다.

    import { NextResponse } from 'next/server'

    return NextResponse.next()

NextResponse.next({ request: { headers } })를 사용해 응답을 생성할 때 headers를 업스트림으로 전달할 수도 있습니다.

    import { NextResponse } from 'next/server'

    // Given an incoming request...
    const newHeaders = new Headers(request.headers)
    // Add a new header
    newHeaders.set('x-version', '123')
    // Forward the modified request headers upstream
    return NextResponse.next({
      request: {
        // New request headers
        headers: newHeaders,
      },
    })

이는 newHeaders를 대상 페이지, 라우트, 서버 액션으로 업스트림 전달하며 클라이언트에는 노출하지 않습니다. 이 패턴은 데이터를 업스트림으로 전달하는 데 유용하지만, 해당 데이터를 포함한 헤더가 외부 서비스로 전달될 수 있으므로 주의해서 사용해야 합니다.

반대로 NextResponse.next({ headers })는 프록시에서 클라이언트로 헤더를 보내는 단축 표기입니다. 이는 좋은 관행이 아니며 피해야 합니다. Content-Type과 같은 응답 헤더를 설정하면 프레임워크의 기대(예: Server Actions가 사용하는 Content-Type)를 덮어써 제출 실패나 스트리밍 응답 중단을 초래할 수 있기 때문입니다.

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

    async function proxy(request: NextRequest) {
      const headers = await injectAuth(request.headers)
      // DO NOT forward headers like this
      return NextResponse.next({ headers })
    }

일반적으로 모든 수신 요청 헤더를 복사하지 마세요. 그렇게 하면 민감한 데이터가 클라이언트나 업스트림 서비스로 유출될 수 있습니다.

허용 목록을 사용해 수신 요청 헤더의 하위 집합을 만드는 방어적 접근을 권장합니다. 예를 들어 사용자 지정 x-* 헤더를 버리고 안전하다고 알려진 헤더만 전달할 수 있습니다.

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

    function proxy(request: NextRequest) {
      const incoming = new Headers(request.headers)
      const forwarded = new Headers()

      for (const [name, value] of incoming) {
        const headerName = name.toLowerCase()
        // Keep only known-safe headers, discard custom x-* and other sensitive ones
        if (
          !headerName.startsWith('x-') &&
          headerName !== 'authorization' &&
          headerName !== 'cookie'
        ) {
          // Preserve original header name casing
          forwarded.set(name, value)
        }
      }

      return NextResponse.next({
        request: {
          headers: forwarded,
        },
      })
    }

보내기