NNext.js 中文网 GitHub

NextResponse

NextResponse 的 API 参考。

NextResponse 通过额外的便捷方法扩展了 Web Response API。

cookies#

读取或修改响应的 Set-Cookie 标头。

set(name, value)#

给定名称,在响应上设置一个具有给定值的 cookie。

ts
// 假设传入请求为 /home
let response = NextResponse.next()
// 设置一个 cookie 来隐藏横幅
response.cookies.set('show-banner', 'false')
// 响应将带有 `Set-Cookie:show-banner=false;path=/home` 标头
return response

get(name)#

给定 cookie 名称,返回该 cookie 的值。如果未找到该 cookie,则返回 undefined。如果找到多个 cookie,则返回第一个。

ts
// 假设传入请求为 /home
let response = NextResponse.next()
// { name: 'show-banner', value: 'false', Path: '/home' }
response.cookies.get('show-banner')

getAll()#

给定 cookie 名称,返回该 cookie 的值。如果未给定名称,则返回响应中的所有 cookie。

ts
// 假设传入请求为 /home
let response = NextResponse.next()
// [
//   { name: 'experiments', value: 'new-pricing-page', Path: '/home' },
//   { name: 'experiments', value: 'winter-launch', Path: '/home' },
// ]
response.cookies.getAll('experiments')
// 或者,获取响应中的所有 cookie
response.cookies.getAll()

has(name)#

给定 cookie 名称,如果该 cookie 存在于响应中,则返回 true。

ts
// 假设传入请求为 /home
let response = NextResponse.next()
// 如果 cookie 存在则返回 true,否则返回 false
response.cookies.has('experiments')

delete(name)#

给定 cookie 名称,从响应中删除该 cookie。

ts
// 假设传入请求为 /home
let response = NextResponse.next()
// 删除成功返回 true,若未删除任何内容则返回 false
response.cookies.delete('experiments')

json()#

生成带有给定 JSON 正文的响应。

app/api/route.ts
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
}
app/api/route.js
import { NextResponse } from 'next/server'

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

redirect()#

生成重定向到 URL 的响应。

ts
import { NextResponse } from 'next/server'

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

URL 可以在用于 NextResponse.redirect() 方法之前创建和修改。例如,你可以使用 request.nextUrl 属性获取当前 URL,然后对其进行修改以重定向到其他 URL。

ts
import { NextResponse } from 'next/server'

// 假设有一个传入请求……
const loginUrl = new URL('/login', request.url)
// 向 /login URL 添加 ?from=/incoming-url
loginUrl.searchParams.set('from', request.nextUrl.pathname)
// 然后重定向到新 URL
return NextResponse.redirect(loginUrl)

rewrite()#

生成一个响应,在保留原始 URL 的同时重写(代理)给定的 URL。

ts
import { NextResponse } from 'next/server'

// 传入请求:/about,浏览器显示 /about
// 重写后的请求:/proxy,浏览器显示 /about
return NextResponse.rewrite(new URL('/proxy', request.url))

next()#

next() 方法对 Proxy 很有用,因为它允许你提前返回并继续路由。

ts
import { NextResponse } from 'next/server'

return NextResponse.next()

你还可以在生成响应时使用 NextResponse.next({ request: { headers } }) 将 headers 转发到上游:

ts
import { NextResponse } from 'next/server'

// 假设有一个传入请求……
const newHeaders = new Headers(request.headers)
// 添加一个新的标头
newHeaders.set('x-version', '123')
// 将修改后的请求标头转发到上游
return NextResponse.next({
  request: {
    // 新的请求标头
    headers: newHeaders,
  },
})

这会将 newHeaders 转发到上游的目标页面、路由或 server action,并且不会将它们暴露给客户端。虽然此模式对于向上游传递数据很有用,但应谨慎使用,因为包含这些数据的标头可能会被转发到外部服务。

相比之下,NextResponse.next({ headers }) 是从 proxy 向客户端发送标头的简写形式。这不是好的做法,应当避免。除其他原因外,因为设置响应标头(如 Content-Type)可能会覆盖框架的预期(例如 Server Actions 使用的 Content-Type),导致提交失败或流式响应中断。

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

async function proxy(request: NextRequest) {
  const headers = await injectAuth(request.headers)
  // 不要像这样转发标头
  return NextResponse.next({ headers })
}

一般来说,避免复制所有传入的请求标头,因为这样做可能会将敏感数据泄露给客户端或上游服务。

更推荐采用防御性方法,使用允许列表创建传入请求标头的子集。例如,你可以丢弃自定义的 x-* 标头,只转发已知安全的标头:

ts
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()
    // 只保留已知安全的标头,丢弃自定义 x-* 标头和其他敏感标头
    if (
      !headerName.startsWith('x-') &&
      headerName !== 'authorization' &&
      headerName !== 'cookie'
    ) {
      // 保留原始标头名称的大小写
      forwarded.set(name, value)
    }
  }

  return NextResponse.next({
    request: {
      headers: forwarded,
    },
  })
}
Next.js 中文网