用途
该技能文档介绍在 Next.js App Router 中，使用 useSearchParams Hook 读取 URL 查询参数时需要遵循的 Suspense 模式。它强调这并非可选项，而是 Next.js 的强制要求。
模式概览
useSearchParams Hook 必须满足两个条件：
- 组件必须带有
'use client'指令。 - 组件必须被
<Suspense>边界包裹。
useSearchParams 用于读取 URL 查询参数，例如 /search?q=shoes 中 searchParams.get('q') 返回 "shoes"；/products?category=electronics&sort=price 可读取多个参数。使用 Suspense 的原因是 Next.js 借助 React 18 的 Suspense 处理在服务端渲染与 hydration 期间读取 URL 参数的异步特性。
主要写法
文档给出两种代码组织方式。
单文件模式（推荐）：页面文件 app/page.tsx 中导入 Suspense 与子组件，用 <Suspense fallback={<div>Loading...</div>}> 包裹子组件；子组件文件 app/SearchComponent.tsx 顶部写 'use client'，并从 next/navigation 导入 useSearchParams。
内联模式（单文件）：在 app/page.tsx 顶部写 'use client'，从 react 导入 Suspense，从 next/navigation 导入 useSearchParams，将使用 Hook 的内部组件用 Suspense 包裹后导出默认页面组件。
TypeScript 方面，文档明确不要使用 any 类型，并指出 useSearchParams 返回 ReadonlyURLSearchParams，get 方法返回 string | null。
读取与更新参数
读取方面，文档演示了 get 获取单个值、getAll 获取同一键的多个值、has 判断键是否存在、forEach 遍历所有参数，以及用 Object.fromEntries(searchParams.entries()) 转换为普通对象。
更新方面，模式为：基于 searchParams.toString() 创建新的 URLSearchParams，用 set 设置值、用 delete 删除空值，然后通过 router.push('?' + params.toString()) 导航。
常见模式
文档给出多个现实场景示例，包括：搜索界面（读取 q 与 category）、产品筛选（结合 useSearchParams 与 useRouter 更新 category、sort、minPrice）、分页（读取与更新 page）、带防抖的搜索输入（300ms）、多条件筛选面板与清除筛选。
常见错误
文档列出三类错误及正确写法：
- 缺少
'use client'：会导致错误，需在文件顶部添加该指令。 - 缺少 Suspense 包裹：会引发问题，需将使用 Hook 的组件放入
<Suspense>。 - 在服务端组件中使用：Hook 不能在服务端组件中使用，服务端组件应改为接收
searchParamsprop，且该 prop 可为Promise并需await。
服务端与客户端对比
文档以表格形式对比：服务端组件通过 searchParams prop 访问，不需要 'use client'，不需要 Suspense，可以异步，不能更新参数（改用 Link/redirect），适合初始加载与 SEO；客户端组件通过 useSearchParams() 访问，需要 'use client'，需要 Suspense，不能异步，可以更新参数（使用 router.push），适合动态筛选与实时更新。
检查清单
使用 useSearchParams 时：在文件顶部添加 'use client'；从 react 导入 Suspense；从 next/navigation 导入 useSearchParams；将使用 Hook 的组件包裹在 <Suspense> 中；为 Suspense 提供 fallback；在被包裹组件内部调用 Hook；使用 .get()、.has() 或 .getAll() 读取参数。
适用场景与限制
该模式适用于客户端读取 URL 参数，如筛选、搜索、分页，并结合 useRouter() 更新参数。它不适用于服务端组件，服务端组件应改用 searchParams prop。文档未提供具体版本号、安装命令、性能数据或价格信息。