Next.js App Router 中处理 POST 请求的正确方式

在 Next.js app router 中定义 API 路由时，必须显式返回 NextResponse 实例；若函数无返回值（即隐式返回 undefined），运行时会因尝试读取 undefined.headers 而抛出 TypeError。

在 next.js app router 中定义 api 路由时，必须显式返回 `nextresponse` 实例；若函数无返回值（即隐式返回 `undefined`），运行时会因尝试读取 `undefined.headers` 而抛出 typeerror。

Next.js App Router 的路由处理器（如 POST、GET）本质上是服务端函数，其返回值会被框架用于构建 http 响应。与 Pages Router 不同，App Router 严格要求每个请求处理器必须返回一个符合 Response 接口的对象——通常是 NextResponse 的实例。若遗漏 return 语句（或返回 undefined、void），Next.js 内部在尝试访问响应对象的 headers 属性时便会触发 TypeError: Cannot read properties of undefined (reading ‘headers’)。

✅ 正确写法：始终返回 NextResponse

// app/api/hello/route.ts import { NextResponse } from 'next/server';  export async function POST(request: Request) {   console.log('Hello world'); // ✅ 日志正常输出   return NextResponse.json({ message: 'Hello world' }, { status: 200 }); }

⚠️ 常见错误示例（会导致报错）：

// ❌ 错误：无返回值 → 隐式返回 undefined export async function POST(request: Request) {   console.log('Hello world'); } // 缺少 return，运行时报 headers 错误  // ❌ 错误：返回原始值（非 Response 对象） export async function POST(request: Request) {   return { message: 'Hello world' }; // 类型不兼容，Next.js 无法处理 }

? 补充说明：

• NextResponse.json()、NextResponse.redirect()、NextResponse.next() 等均为标准响应构造器，自动设置对应状态码与 Content-Type 头；
• 若需自定义响应头，可传入第二个参数（Init 对象）：

  return NextResponse.json({ ok: true }, {   status: 201,   headers: { 'X-Custom': 'app-router' } });

• 所有路由处理器默认为异步函数（推荐显式声明 async），便于后续处理 request.json() 或数据库调用等异步操作。

? 总结：在 App Router 中，每个请求方法都必须返回一个有效的 Response 对象。这是框架底层响应组装机制的硬性要求，而非可选约定。养成“先写 return，再写逻辑”的习惯，可有效规避此类运行时错误。