Next.js Proxy详解：请求代理与中间件实践 1. Next.js中的Proxy是什么Proxy在Next.js中扮演着请求拦截和处理的角色。从Next.js 16开始原本的Middleware功能被重命名为Proxy这个变化更准确地反映了其核心功能——作为请求和响应之间的代理层。Proxy允许你在请求完成前执行自定义逻辑根据请求内容动态修改响应行为。重要提示Proxy文件必须命名为proxy.ts或proxy.js且每个项目只能有一个这样的文件。虽然只能有一个入口文件但你可以通过模块化方式组织代码将不同路由的代理逻辑拆分到单独文件中再导入。Proxy的典型应用场景包括动态修改请求/响应头如添加CORS头、修改缓存控制基于A/B测试的路由重写根据用户属性进行程序化跳转请求预处理如权限校验、参数标准化2. 为什么需要Proxy2.1 传统方案的局限性在没有Proxy的情况下开发者通常需要在页面组件或API路由中处理这些逻辑。这会导致代码重复相同的校验逻辑需要在多个地方实现关注点混杂业务逻辑与基础设施代码耦合性能损耗每次请求都需要完整加载页面逻辑2.2 Proxy的架构优势Proxy运行在Edge Runtime环境中具有以下特点前置执行在请求到达页面/API前处理轻量级不加载React等重型依赖全局作用一次编写多处生效// 典型Proxy结构示例 import { NextResponse } from next/server import type { NextRequest } from next/server export function proxy(request: NextRequest) { const url request.nextUrl if (url.pathname.startsWith(/admin)) { // 权限校验逻辑 } return NextResponse.next() }3. 核心配置与实现3.1 文件约定Proxy文件必须位于以下位置之一项目根目录下的proxy.ts/proxy.jssrc目录下的proxy.ts/proxy.js3.2 匹配器配置通过matcher配置控制Proxy的生效范围export const config { matcher: [ /api/:path*, // 匹配所有API路由 /((?!_next).*), // 排除_next静态资源 /dashboard/:path* // 匹配特定路径 ] }匹配规则支持静态路径/about动态参数/user/:id通配符/api/*正则表达式/((?!_next).*)3.3 响应处理Proxy可以返回多种响应类型响应类型方法典型场景继续处理NextResponse.next()添加监控头信息重定向NextResponse.redirect()权限校验失败跳转重写NextResponse.rewrite()A/B测试路由直接响应NextResponse.json()拦截非法请求4. 实战应用场景4.1 跨域处理export function proxy(request: NextRequest) { const response NextResponse.next() response.headers.set(Access-Control-Allow-Origin, *) response.headers.set(Access-Control-Allow-Methods, GET, POST) return response }4.2 权限校验export async function proxy(request: NextRequest) { const session await getSession(request.cookies) if (!session request.nextUrl.pathname.startsWith(/protected)) { return NextResponse.redirect(new URL(/login, request.url)) } return NextResponse.next() }4.3 多租户支持export function proxy(request: NextRequest) { const host request.headers.get(host) const tenant getTenantFromHost(host) request.headers.set(x-tenant-id, tenant.id) return NextResponse.next({ headers: request.headers }) }5. 性能优化与调试5.1 避免常见性能陷阱不要进行重型计算Proxy运行在Edge环境CPU资源有限减少外部调用避免在Proxy中进行数据库查询等IO操作合理设置缓存对稳定逻辑使用NextResponse.next()的缓存选项5.2 调试技巧使用console.log输出会显示在Edge Runtime日志中通过request.nextUrl查看完整URL信息利用request.headers和request.cookies获取请求上下文export function proxy(request: NextRequest) { console.log(Incoming request to:, request.nextUrl.pathname) console.log(Cookies:, request.cookies.getAll()) return NextResponse.next() }6. 高级模式与限制6.1 模块化组织虽然只能有一个proxy文件但可以通过模块化保持代码整洁/src /middleware auth.ts cors.ts logging.ts proxy.ts// proxy.ts import { authMiddleware } from ./middleware/auth import { corsMiddleware } from ./middleware/cors export function proxy(request: NextRequest) { const authResponse authMiddleware(request) if (authResponse) return authResponse const corsResponse corsMiddleware(request) return corsResponse || NextResponse.next() }6.2 已知限制无数据获取不能在Proxy中使用fetch获取数据文件大小限制Edge Function有代码大小限制冷启动延迟首次调用可能有100-300ms延迟7. 与类似功能的对比功能ProxyAPI RoutesgetServerSideProps执行时机请求最早阶段路由匹配后页面渲染前运行环境EdgeServerServer典型用途请求预处理数据接口服务端渲染性能影响最低中等最高8. 错误处理实践8.1 捕获异常export function proxy(request: NextRequest) { try { // 业务逻辑 } catch (error) { console.error(Proxy error:, error) return NextResponse.json( { error: Internal Server Error }, { status: 500 } ) } }8.2 常见错误排查404错误检查matcher配置是否覆盖目标路由502错误确保Proxy函数有返回值CORS问题验证响应头是否正确设置重定向循环检查重定向条件逻辑9. 部署注意事项环境变量使用process.env访问的变量需要在部署平台预先配置地域选择选择靠近用户的Edge区域部署版本控制Proxy更新后可能需要清除CDN缓存10. 实际项目中的经验在大型电商项目中我们使用Proxy实现了基于地理位置的定价重定向黑名单IP拦截灰度发布控制关键收获保持Proxy逻辑精简复杂业务应移交给API处理为所有Proxy操作添加日志记录使用Feature Flag控制新功能的逐步发布// 灰度发布示例 export function proxy(request: NextRequest) { const url request.nextUrl const isNewFeatureEnabled Math.random() 0.1 // 10%流量 if (isNewFeatureEnabled url.pathname /checkout) { url.pathname /checkout-v2 return NextResponse.rewrite(url) } return NextResponse.next() }