当前位置：首页 > news >正文

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

news 2025/11/2 11:27:11

在 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.pathnameconst 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