**这是本文档旧的修订版!**
原先是中间件,2025年改为代理
CVE-2025-29927(2025 年 3 月,CVSS 9.1):攻击者伪造 x-middleware-subrequest 请求头即可完全跳过 middleware 执行,当时官方通告的原话就是“如果授权检查发生在 middleware 里,就可能被绕过”——已在 12.3.5 / 13.5.9 / 14.2.25 / 15.2.3 修复,但教训保留了下来
因此:proxy 里只做“乐观检查”(optimistic check)——为了体验和性能做的快速拦截,真正的授权必须落在路由处理函数和数据访问层再校验一次
一句话:proxy 是路由层,不是锁。锁要装在门里面(服务端)。
https://nextjs.org/docs/app/api-reference/file-conventions/proxy
一、Proxy 是什么、主要职责
它是位于路由匹配之前执行的单一函数,能对每个进来的请求做四件事:
| 职责 | 典型场景 |
| Redirect(重定向) | 未登录跳 /login、旧 URL 迁移、http→https |
| Rewrite(改写) | A/B 测试分流、按 locale 改写路径、把 /api/* 转发到内部后端地址(对外隐藏真实接口路径) |
| Header/Cookie 操作 | 注入安全头(CSP、X-Frame-Options)、读写 cookie(会话、实验分组) |
| 直接返回响应 | 健康检查、简单限流拦截,不进入后续路由 |
典型代码:
- snippet.javascript
// proxy.ts(项目根目录,或 src/ 下,与 app/ 同级) import { NextRequest, NextResponse } from "next/server"; export function proxy(req: NextRequest) { const session = req.cookies.get("session"); if (!session && req.nextUrl.pathname.startsWith("/admin")) { return NextResponse.redirect(new URL("/login", req.url)); } return NextResponse.next(); // 放行 } export const config = { matcher: ["/admin/:path*"], // 只对匹配的路径生效 };
它还能访问完整的 Node.js API(文件、原生库等),因为新 proxy 只跑 Node.js 运行时,不再支持 Edge runtime,也不允许配置 runtime 选项——设了会直接报错。如果你强依赖 Edge,暂时只能留在旧的 middleware.ts。