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

Next.js 13 API 路由中正确解析 query 参数的完整指南

Next.js 13 App Router 中的 API 路由不再支持 req.query，必须通过 request.nextUrl.searchParams 获取查询参数，且需使用命名导出（如 GET）而非默认导出函数。

next.js 13 app router 中的 api 路由不再支持 `req.query`，必须通过 `request.nexturl.searchparams` 获取查询参数，且需使用命名导出（如 `get`）而非默认导出函数。

在 Next.js 13 及更高版本的 App Router 中，API 路由（位于 app/api/.../route.ts 或 .js）已彻底重构：它不再兼容 Pages Router 的 req/res 处理模式，也不再提供 req.query 属性。你遇到的 TypeError: Cannot destructure property 'filterBy' of 'request.query' as it is undefined 错误，根本原因正是试图沿用旧范式——而 request.query 在 App Router 中根本不存在。

✅ 正确做法是：

使用 NextRequest 类型（推荐 TypeScript）或直接访问 request.nextUrl.searchParams；
以命名导出方式定义 HTTP 方法处理器（如 export async function GET(request) { ... }）；
通过 URLSearchParams API 安全提取参数（支持 .get()、.getAll()、解构需手动转换）。

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

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

// 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 报错）
  const filters: Record<string string> = {};
  for (const [key, value] of searchParams.entries()) {
    if (key !== 'filterBy') filters[key] = value;
  }

  try {
    await connectToMongoDB();
    let events = await Event.find({});

    if (filterBy === 'status' && status) {
      events = await Event.find({ status });
    }

    return NextResponse.json({ events }, { status: 200 });
  } catch (error) {
    console.error('API route error:', error);
    return NextResponse.json(
      { error: 'Failed to fetch events' },
      { status: 500 }
    );
  }
}</string>

? 关键注意事项：

❌ 不要使用 export default async (req, res) => { ... } —— App Router 下该签名无效，且 req 并非 Express-like 对象；
✅ request.nextUrl 是一个 NextURL 实例（继承自原生 URL），其 searchParams 属性即标准 URLSearchParams；
? 若需批量提取所有参数并排除特定键（如 filterBy），推荐使用 for...of searchParams.entries() 循环，而非尝试解构 undefined 对象；
? 客户端调用方式无需更改：fetch('/api/events?filterBy=status&status=Live') 依然有效，服务端只需按新规范解析；
⚠️ 若同时使用 getServerSideProps，注意它运行在服务端，但调用的是同源 API 路由——确保路由路径正确（如 /api/events），且无跨域或中间件拦截问题。

总结：Next.js App Router 的 API 路由是基于 Web Standards（Request/Response）构建的现代化接口，拥抱 URLSearchParams 和显式 HTTP 方法导出，既是升级要求，也是更可维护、类型安全和符合平台演进的最佳实践。