从0死磕全栈之深入理解 Next.js 中的 NextResponse：API 详解与实战示例

在 Next.js 的 App Router 架构中，NextResponse 是一个强大而灵活的工具，用于在 Middleware 、Route Handlers （API 路由）等服务器端逻辑中构造 HTTP 响应。它扩展了原生的 Web Response API，并提供了许多便捷方法，如设置 Cookie、重定向、重写路径、返回 JSON 等。

---

1. 基础用法：NextResponse.next()

next() 方法常用于 Middleware 中，表示"继续处理后续路由"，同时允许你修改请求或响应。

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

export function middleware(request: NextRequest) {
  // 添加自定义请求头
  const newHeaders = new Headers(request.headers)
  newHeaders.set('x-custom-version', '1.0.0')

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

✅ 用途：权限校验、A/B 测试、国际化路由等场景中"放行"请求。

---

2. 设置与操作 Cookie

NextResponse 提供了对 Set-Cookie 响应头的便捷操作。

设置 Cookie

// middleware.ts
import { NextResponse } from 'next/server'

export function middleware() {
  const response = NextResponse.next()
  response.cookies.set('show-banner', 'false', {
    path: '/home',
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
  })
  return response
}

📌 生成的响应头：

Set-Cookie: show-banner=false; Path=/home; HttpOnly; Secure

读取 Cookie

const bannerCookie = response.cookies.get('show-banner')
// 返回 { name: 'show-banner', value: 'false', Path: '/home' } 或 undefined

获取所有 Cookie

// 获取指定名称的所有 Cookie（支持多值）
const experiments = response.cookies.getAll('experiments')

// 获取所有 Cookie
const allCookies = response.cookies.getAll()

删除 Cookie

const deleted = response.cookies.delete('show-banner') // 返回 boolean

💡 注意：delete() 实际是设置该 Cookie 的过期时间为过去，从而让浏览器删除它。

---

3. 返回 JSON 响应：NextResponse.json()

在 Route Handler（如 app/api/user/route.ts）中非常常用：

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

export async function GET() {
  return NextResponse.json(
    { id: 1, name: 'Alice' },
    { status: 200 }
  )
}

export async function POST() {
  return NextResponse.json(
    { error: 'Invalid input' },
    { status: 400 }
  )
}

✅ 自动设置 Content-Type: application/json。

---

4. 重定向：NextResponse.redirect()

用于身份验证、URL 规范化等场景。

// middleware.ts
import { NextResponse } from 'next/server'

export function middleware(request: NextRequest) {
  const isLoggedIn = false // 假设未登录

  if (!isLoggedIn) {
    const loginUrl = new URL('/login', request.url)
    loginUrl.searchParams.set('from', request.nextUrl.pathname)
    return NextResponse.redirect(loginUrl)
  }

  return NextResponse.next()
}

🔁 会返回 307 Temporary Redirect（或 308，取决于方法）。

---

5. 路径重写：NextResponse.rewrite()

与重定向不同，重写不会改变浏览器地址栏 URL，但会内部代理到另一个路径。

// middleware.ts
import { NextResponse } from 'next/server'

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname === '/secret') {
    // 用户访问 /secret，但实际渲染 /internal-page 的内容
    return NextResponse.rewrite(new URL('/internal-page', request.url))
  }

  return NextResponse.next()
}

🌐 适用于：动态内容代理、A/B 测试、隐藏真实路径等。

---

6. 完整示例：带认证的 Middleware

结合多种能力，实现一个简单的登录拦截器：

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

const PUBLIC_PATHS = ['/login', '/signup', '/about']

export function middleware(request: NextRequest) {
  const path = request.nextUrl.pathname
  const token = request.cookies.get('auth-token')?.value

  // 公开路径直接放行
  if (PUBLIC_PATHS.some(p => path.startsWith(p))) {
    return NextResponse.next()
  }

  // 未登录则重定向到登录页
  if (!token) {
    const loginUrl = new URL('/login', request.url)
    loginUrl.searchParams.set('from', path)
    return NextResponse.redirect(loginUrl)
  }

  // 已登录：设置安全头并继续
  const response = NextResponse.next()
  response.cookies.set('last-visited', path, { maxAge: 60 * 60 }) // 1小时
  return response
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
}

---

总结

NextResponse 是 Next.js App Router 中处理服务器响应的核心工具，其主要能力包括：

方法	用途
next()	继续路由（Middleware）
json()	返回 JSON 响应
redirect()	重定向用户
rewrite()	内部重写路径（不改变 URL）
cookies.set/get/delete	操作响应 Cookie

通过合理使用这些方法，你可以构建高性能、安全且用户体验良好的 Next.js 应用。