Next.js 14 API路由无法获取URL查询参数的问题求助

API 探路者

2026-6-30

回答

问题根源

页面地址栏的q参数是前端路由的查询参数，你的API路由/api/products并没有收到这个参数——因为你没有在调用API时将页面的查询参数传递过去。前端路由更新只是改变了浏览器地址，不会自动把参数附加到API请求里，所以API自然拿不到q的值。

解决步骤

1. 在页面组件中传递查询参数到API

假设商品列表页面是app/products/page.tsx，需要在这个页面里获取当前的q参数，然后拼接到API请求URL中：

// app/products/page.tsx
import Search from '@/components/Search';
import { useSearchParams } from 'next/navigation';

// 封装API请求函数
async function getProducts(query: string | null) {
  const apiUrl = new URL('/api/products', process.env.NEXT_PUBLIC_BASE_URL || 'http://localhost:3000');
  if (query) {
    apiUrl.searchParams.set('q', query);
  }
  const response = await fetch(apiUrl.href, { next: { revalidate: 30 } });
  if (!response.ok) throw new Error('Failed to fetch products');
  return response.json();
}

export default async function ProductsPage() {
  const searchParams = useSearchParams();
  const searchQuery = searchParams.get('q');
  const products = await getProducts(searchQuery);

  return (
    <div className="container mx-auto p-4">
      <Search placeholder="搜索商品..." />
      {/* 渲染商品列表 */}
      <div className="mt-4">
        {products.length > 0 ? (
          <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>
        ) : (
          <p>暂无商品</p>
        )}
      </div>
    </div>
  );
}

2. 验证API路由的正确性

你的API路由代码本身没有问题，只要请求URL包含q参数，就能正确获取并自动解码空格（比如test+search+product会被解析为test search product）。可以直接在浏览器访问http://localhost:3000/api/products?q=test+search+product，此时API响应应该返回{"query":"test search product"}。

额外注意事项

如果是在客户端组件中调用API，同样可以用useSearchParams获取当前页面的查询参数，再拼到API请求里。
服务器组件中调用API时，建议使用绝对URL（可以通过环境变量NEXT_PUBLIC_BASE_URL配置），避免路径解析错误。
若需要实时搜索，可以在客户端组件中使用useEffect监听searchParams变化，再触发API请求。

内容的提问来源于stack exchange，提问作者eunoya