Next.js项目本地与Vercel构建失败：useSearchParams问题求助

问题现象 #

本地及Vercel平台构建Next.js项目时失败，报错信息：

Export encountered errors on following paths: /(dashboard)/dashboard/edit-resume/page: /dashboard/edit-resume error Command failed with exit code 1.

注释useSearchParams相关代码后构建可成功完成，尝试使用Suspense组件无法解决问题。

相关代码片段：

import { useSearchParams } from "next/navigation";

const router = useRouter();
const searchParams = useSearchParams();
const search = searchParams.get("template");
console.log("queryParams", search);

return (
    <Suspense fallback={<Loader size="lg" />}>
        <div className="flex flex-col md:flex-row">
            // other codes
        </div>
    </Suspense>
);

原因分析 #

Next.js默认静态构建时会预渲染所有页面，而useSearchParams是客户端专属API，只能在浏览器运行时获取URL参数。静态构建阶段没有浏览器环境，无法解析运行时的URL参数，因此直接在页面组件中调用会触发构建错误。Suspense仅用于处理异步数据加载的状态，无法解决API本身在静态阶段不可用的问题。

解决方案 #

方案1：标记页面为动态渲染 #

在页面文件（page.js）顶部添加动态配置，强制页面每次请求都在服务器端运行，从而支持获取searchParams：

// /(dashboard)/dashboard/edit-resume/page.js
export const dynamic = 'force-dynamic';

import { useSearchParams } from "next/navigation";

export default function EditResumePage() {
  const searchParams = useSearchParams();
  const search = searchParams.get("template");
  console.log("queryParams", search);

  return (
    <div className="flex flex-col md:flex-row">
      {/* other codes */}
    </div>
  );
}

注意：如果使用next export做纯静态导出，此方案不适用，需改用Vercel的服务器渲染/边缘渲染模式。

方案2：拆分客户端组件 #

将使用useSearchParams的逻辑封装到单独的客户端组件中，用'use client'指令标记，避免在服务器端渲染时执行客户端API：

1. 创建客户端组件（比如TemplateSearch.js）：

'use client';

import { useSearchParams } from "next/navigation";

export default function TemplateSearch() {
  const searchParams = useSearchParams();
  const template = searchParams.get("template");
  console.log("queryParams", template);

  // 可根据参数渲染内容或传递给父组件
  return <div>当前模板：{template || "默认模板"}</div>;
}

2. 在页面组件中导入并使用该客户端组件：

// /(dashboard)/dashboard/edit-resume/page.js
import { Suspense } from 'react';
import TemplateSearch from './TemplateSearch';
import Loader from './Loader';

export default function EditResumePage() {
  return (
    <Suspense fallback={<Loader size="lg" />}>
      <div className="flex flex-col md:flex-row">
        <TemplateSearch />
        {/* other codes */}
      </div>
    </Suspense>
  );
}

此方案兼容静态导出，因为客户端组件仅在浏览器运行时执行useSearchParams。

方案3：静态导出时兼容无参数场景（不推荐） #

如果必须纯静态导出，可通过判断浏览器环境避免构建阶段报错，但可能引发hydration不匹配，需谨慎使用：

'use client';

import { useSearchParams } from "next/navigation";

export default function EditResumePage() {
  let template = 'default';
  if (typeof window !== 'undefined') {
    const searchParams = useSearchParams();
    template = searchParams.get("template") || 'default';
  }

  return (
    <div className="flex flex-col md:flex-row">
      {/* other codes */}
    </div>
  );
}

内容的提问来源于stack exchange，提问作者Md Neamul Haque Noman