Next.js 13+ API 路由中正确获取 query 参数的完整指南-js教程-PHP中文网

在 Next.js 13 的 App Router 中，API 路由不再支持 req.query 解构，必须使用 request.nextUrl.searchParams 获取 URL 查询参数，否则会报 Cannot destructure property 'xxx' of 'request.query' as it is undefined 错误。

在 next.js 13 的 app router 中，api 路由不再支持 `req.query` 解构，必须使用 `request.nexturl.searchparams` 获取 url 查询参数，否则会报 `cannot destructure property 'xxx' of 'request.query' as it is undefined` 错误。

Next.js 13 引入了全新的 App Router 架构，其 API 路由（位于 app/api/.../route.ts/js）与旧版 Pages Router 完全不同：它不接收 (req, res) 参数，也不提供 req.query 对象。你当前代码中沿用 Pages Router 的写法——export default async (req, res) => { ... }——在 App Router 下不仅无效，还会导致 req.query is undefined 这类运行时错误。

✅ 正确做法是：

使用命名导出（如 GET, POST）代替默认导出；
通过 NextRequest 实例的 nextUrl.searchParams 属性解析查询参数；
利用 URLSearchParams API 安全读取、解构或批量提取参数。

以下是修复后的完整示例：

php版微信js-sdk支付接口类

下载

// app/api/events/route.ts
import { NextRequest, NextResponse } from 'next/server';
import Event from '@models/Event';
import { connectToMongoDB } from '@utils/database/connectToMongoDB';

export async function GET(request: NextRequest) {
  // ✅ 正确获取 query 参数
  const searchParams = request.nextUrl.searchParams;
  const filterBy = searchParams.get('filterBy'); // string | null
  const status = searchParams.get('status');

  // ✅ 安全解构（避免 null/undefined 报错）
  const filters = Object.fromEntries(
    Array.from(searchParams.entries()).filter(([key]) => key !== 'filterBy')
  );

  // 可选：类型断言或验证
  if (!filterBy || !['status', 'category', 'date'].includes(filterBy)) {
    return NextResponse.json({ error: 'Invalid filterBy value' }, { status: 400 });
  }

  try {
    await connectToMongoDB();
    const events = await Event.find(filters).exec();
    return NextResponse.json({ data: events });
  } catch (error) {
    console.error('API route error:', error);
    return NextResponse.json({ error: 'Failed to fetch events' }, { status: 500 });
  }
}

? 关键注意事项：

不要使用 req.query：App Router 中 req 是 NextRequest 实例，无 query 属性；
避免 searchParams.getAll() 直接解构：searchParams.get() 返回 string | null，需做空值判断；若需多值（如 ?tag=a&tag=b），用 searchParams.getAll('tag')；
客户端调用保持不变：fetch('/api/events?filterBy=status&status=Live') 完全兼容，无需修改；
服务端渲染（如 getServerSideProps）已弃用：App Router 中应改用 async Server Component + fetch 或 generateStaticParams 等新范式；若仍在用 getServerSideProps，说明项目混合了 Pages Router 和 App Router，建议统一迁移。

总结：Next.js App Router 的 API 路由是基于 Web Standard 的 Request/Response 模型，拥抱 URLSearchParams 和显式 HTTP 方法导出，是更现代、更可预测的设计。及时更新路由签名和参数解析方式，是避免此类错误的根本方案。