Next.js 13+ 的 App Router 引入了基于 Response 对象的全新 API 路由范式，取代了 Pages Router 中基于 req/res 的 Express 风格处理方式，提升了可测试性、跨环境兼容性与框架集成度。
next.js 13+ 的 app router 引入了基于 `response` 对象的全新 api 路由范式，取代了 pages router 中基于 `req/res` 的 express 风格处理方式，提升了可测试性、跨环境兼容性与框架集成度。
在 Next.js 的演进过程中，API 路由的实现方式发生了根本性变化——从 Pages Router 的 Node.js 服务器依赖模式，转向 App Router 的标准化 Web API 模式。这一转变不仅体现为语法差异，更反映了 Next.js 向边缘运行时（Edge Runtime）、服务端组件（Server Components）和统一数据流架构的深度演进。
✅ 核心差异：从 req/res 到 Request/Response
-
Pages Router（旧）：
使用pages/api/xxx.js，导出handler(req, res)，依赖 Node.js 的http.ServerResponse（如res.status(200).json(...)）。该模式紧密耦合于 Node.js 环境，难以在非 Node 环境（如 Vercel Edge Functions、Deno、Cloudflare Workers）中运行或单元测试。// pages/api/code.js export default async function handler(req, res) { res.status(200).json({ message: "successful" }); } -
App Router（新）：
使用app/api/xxx/route.js，按 HTTP 方法导出命名函数（如GET,POST），仅接收Request对象（无res参数），必须显式返回Response实例：// app/api/code/route.js export async function POST(request) { const body = await request.json(); return Response.json( { message: "successful" }, { status: 201 } ); }
✅ 推荐使用
Response.json()辅助方法（自动设置Content-Type: application/json和序列化），而非手动new Response(JSON.stringify(...), {...})—— 更安全、简洁、语义清晰。
? 为什么弃用 res？设计哲学解析
环境无关性（Environment Agnosticism）：
Response是 Web 标准（WHATWG 规范）的一部分，被所有现代运行时（Node.js、Vercel Edge、Cloudflare Workers、Deno）原生支持；而res.end()等方法是 Node.js 特有的。这使得同一段路由代码可在不同部署目标无缝运行。可测试性跃升：
你可直接构造new Request('http://localhost/api/code', { method: 'POST', body: JSON.stringify({...}) })并调用POST(request)，断言返回的Response实例，无需启动 HTTP 服务器或 mockres对象。与 React Server Components 深度协同：
App Router 的整个数据获取层（fetch、async Server Components、generateStaticParams）均基于 Promise 和标准 Web API，统一的数据流模型降低了心智负担与错误边界。
⚠️ 注意事项与最佳实践
-
❌ 错误写法（
res参数无效且被忽略）：
Json Schema Toolkit下载使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
export const GET = async (req, res) => { /* res is unused! */ } // 不报错但无意义 -
✅ 正确签名（仅
request）：export async function GET(request) { ... } export async function POST(request) { ... } -
✅ 支持中间件式逻辑（如鉴权、日志）：
export async function POST(request) { const authHeader = request.headers.get('Authorization'); if (!authHeader) return Response.json({ error: 'Unauthorized' }, { status: 401 }); const data = await request.json(); return Response.json({ success: true, received: data }); } -
✅ 自动 Content-Type 处理（推荐）：
// ✅ 自动设置 headers + JSON stringify return Response.json({ message: "ok" }, { status: 200 }); // ❌ 手动处理易出错（如忘记 header） return new Response(JSON.stringify({ message: "ok" }), { status: 200, headers: { 'Content-Type': 'application/json' } });
? 总结
Next.js App Router 的 API 路由不是简单的语法糖升级，而是面向未来部署场景（边缘计算、全栈 Server Components）的架构重构。它以标准 Request/Response 为核心，解耦运行时依赖，提升可移植性与可维护性。迁移时请牢记：没有 res，只有 return Response；没有隐式响应，只有显式、可组合、可测试的 Web 响应对象。
