Next.js 15服务端获取searchParams报错问题排查

问题本质 #

你遇到的两类报错核心都是路由渲染模式与searchParams的动态特性不兼容：

• 直接读取searchParams.code时，Next.js 15要求必须先await searchParams才能访问其属性（因searchParams为动态加载的对象）；
• 声明searchParams为Promise并await后，路由配置的dynamic = "error"强制静态渲染，而动态的searchParams只能在动态渲染路由中使用，两者冲突。

解决方案 #

步骤1：调整路由渲染模式

在目标路由文件（app/example-folder/my-route/page.tsx）中，添加动态渲染配置，禁用静态渲染：

// 显式设置路由为动态渲染，适配searchParams的动态特性
export const dynamic = "force-dynamic";

export default async function SelectPhotosPage({
  searchParams,
}: {
  searchParams: Promise<Record<string, string | string[]> | undefined>;
}) {
  // 先await获取实际的参数对象
  const params = await searchParams;
  // 提取code参数，处理参数不存在的情况
  const code = params?.code;

  if (!code) {
    return <div>缺少必要的code参数</div>;
  }

  const responseData = await exchangeCodeForToken({ code });
  // 后续业务逻辑...
  return <div>处理完成</div>;
}

关键说明

• 为什么要await searchParams：Next.js 15中服务端组件的searchParams是Promise类型，必须通过await获取实际参数对象，否则直接访问属性会触发「同步使用动态API」的报错；
• 为什么要设置dynamic="force-dynamic"：静态渲染是在构建阶段生成页面，而searchParams是请求时的动态值，无法提前预知，因此必须显式开启动态渲染，避免静态渲染失败；
• 类型规范：使用Promise<Record<string, string | string[]> | undefined>是官方推荐的searchParams类型，覆盖了参数不存在、多值参数等场景。

替代方案：自动判断渲染模式

若希望Next.js自动适配渲染模式，可将dynamic设置为默认的"auto"（需确保未手动设置过"error"或"force-static"）：

export const dynamic = "auto";

此时Next.js会根据路由是否使用动态数据（如searchParams）自动切换渲染模式，无需强制指定"force-dynamic"。

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