Next.js App Router无/pages目录时，useSearchParams出现'searchParams' is possibly 'null'错误的原因咨询

嘿，我最近在开发一个纯App Router的Next.js项目（完全没用到Pages Router），之前打包都好好的，突然运行next build就报TypeScript错误了，提示Type error: 'searchParams' is possibly 'null'，给我整懵了，来跟大家聊聊细节，求帮忙看看为啥会这样！

我的开发环境 #

• 系统：Windows 11
• Next.js版本：v15.3.2
• Node.js版本：v22.13.1
• NPM版本：v11.4.1
• ORM：Prisma v6.8.2

触发错误的代码 #

我写的代码是这样的，一个用Suspense包裹的客户端组件，里面用了useSearchParams：

'use client';
import { useSearchParams } from 'next/navigation';
import { Suspense, useEffect } from 'react';

function Onboarding() {
  const searchParams = useSearchParams();
  const reason = searchParams.get('reason'); // 这里就触发了"searchParams可能为null"的错误

  useEffect(() => {
    if (reason) {
      // 这里是处理reason的业务逻辑
    }
  }, [reason]);

  // 其他组件代码...
}

export default function OnBoardingWrapper() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Onboarding />
    </Suspense>
  );
}

我翻遍了最近的提交记录，也没找到哪项改动会导致这个问题，真的很困惑。

我已经尝试过的排查步骤 #

1. 首先我查了错误原因，知道是TypeScript认为searchParams可能是null，但按我对Next.js的理解，纯App Router项目里useSearchParams应该只返回ReadonlyURLSearchParams类型，不会有null的情况啊。
2. 然后我去翻了Next.js的文档，看到这段说明：

如果应用包含/pages目录，useSearchParams会返回ReadonlyURLSearchParams | null。这个null是为了迁移兼容，因为在不使用getServerSideProps的页面预渲染期间，无法知道搜索参数。

但我百分百确定我的项目根目录里没有/pages文件夹，全程用的App Router的/app目录，所以按道理不该有这个问题。

我的问题 #

为啥我在完全没有/pages目录的纯App Router项目里，还是会碰到'searchParams' is possibly 'null'的TypeScript错误呢？有没有朋友碰到过类似的情况，或者知道怎么解决？

可能的解决思路 #

结合社区案例和自己的排查经验，整理了几个方向供参考：

• 检查残留的Pages Router相关文件/配置：虽然你没建/pages目录，但可能不小心创建了比如pages/_app.tsx这类文件，或者next.config.js里配置了pageExtensions包含旧的页面后缀，导致Next.js误以为是混合路由模式。可以全局搜一下项目里有没有pages相关的文件，或者检查next.config.js的配置。
• 清理TypeScript和Next.js缓存：有时候缓存会导致类型识别异常，试试删除.next文件夹和node_modules/.cache目录，然后重新npm install再打包，说不定能解决。
• 检查Next.js版本的bug：你用的v15.3.2可能存在类型定义的小bug，试试升级到最新稳定版，或者回退到之前打包正常的版本，看看错误是否消失。
• 临时添加空值检查规避：如果急着打包，可以先给searchParams加个可选链或者空值判断，比如const reason = searchParams?.get('reason')，或者在使用前先判断if (!searchParams) return <Loading />，先绕过这个错误，再慢慢排查根源。

内容来源于stack exchange