在 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，再写逻辑”的习惯，可有效规避此类运行时错误。
