如何在 Next.js App Router 中正确创建 API 路由-js教程-PHP中文网

next.js 13+ 的 app router 不再支持在 app/ 目录下使用 page.tsx 创建 api，而应通过专用的 route.ts（或 route.js）文件定义路由处理器，配合标准 http 方法导出函数实现 restful api。

next.js 13+ 的 app router 不再支持在 app/ 目录下使用 page.tsx 创建 api，而应通过专用的 route.ts（或 route.js）文件定义路由处理器，配合标准 http 方法导出函数实现 restful api。

在 Next.js 13.4+（尤其是采用 App Router 的新项目）中，API 路由的实现方式已发生根本性变化：不再复用页面组件机制（如 page.tsx），而是引入专用于服务端逻辑的 route.ts 文件。该文件需放置于 app/ 目录下的任意路由段中（例如 app/api/users/），并导出对应 HTTP 方法（GET、POST 等）的处理函数。

✅ 正确创建 API 路由的步骤

创建路由目录结构
在 app/ 下新建 API 路径，例如：

app/
└── api/
    └── users/
        └── route.ts  ← 关键：必须命名为 route.ts（或 route.js）

编写 route.ts 处理器
使用标准 Web Request/Response API，返回 Response 对象：

// app/api/users/route.ts
export async function GET(request: Request) {
  // 可解析查询参数
  const { searchParams } = new URL(request.url);
  const id = searchParams.get('id');

  // 模拟数据响应
  const data = id ? { id, name: `User ${id}` } : { users: ['Alice', 'Bob'] };

  return Response.json(data, { status: 200 });
}

export async function POST(request: Request) {
  const body = await request.json();
  // 处理创建逻辑（如存入数据库）
  return Response.json({ success: true, data: body }, { status: 201 });
}

⚠️ 注意：同一路径下不可同时存在 page.tsx 和 route.ts（Next.js 会报错）。API 路由与页面路由必须严格分离——route.ts 仅用于 API，page.tsx 仅用于渲染 UI。

Wjs Localizing Video
用于端到端视频本地化流程的轻量编排器，路由至四个专注子技能——/wjs-transcribing-audio、/wjs-translating-subtitles...

下载

? 在页面中调用该 API

在 app/user/page.tsx 中，可通过客户端 fetch 或服务端 fetch（推荐 SSR 场景）调用：

// app/user/page.tsx
export default async function UserPage() {
  const res = await fetch('http://localhost:3000/api/users');
  const users = await res.json();

  return (
    <div>
      <h1>Users</h1>
      <ul>{users.users.map((u: string) => <li key="{u}">{u}</li>)}</ul>
</div>
  );
}

? 关键注意事项

✅ route.ts 必须导出命名函数（如 GET, POST, PUT, DELETE），不支持默认导出；
✅ 支持中间件式逻辑（如身份验证、日志），可直接在函数内处理 request.headers、cookies 等；
❌ 禁止在 app/api/users/page.tsx 中写 API —— 这会被视为普通页面，无法接收请求体或设置状态码；
? 所有 route.ts 自动启用服务端执行，无客户端 bundle 开销，天然支持流式响应（Response.stream()）和 async/await；
? 官方文档参考：Route Handlers

遵循此模式，即可在 App Router 架构下构建清晰、高性能且符合 Next.js 最佳实践的 API 层。