企业官网建设流程全解析

• 前端
• 状态管理

本文介绍如何在仍使用 React Router v5（react-router-dom@^5）的 React 应用中接入 nuqs，把useState的体验带到 URL query string。你将掌握NuqsAdapter的挂载方式、官方注册表提供的适配器源码，以及这套适配器机制（React Context +updateUrl）的底层原理，同时了解该适配器在nuqs@^2生命周期内的兼容性边界。

nuqs（next-usequerystate）从 2.x 开始通过「适配器（Adapter）」机制把类型安全的 URL 状态管理能力开放给 React Router、Remix、TanStack Router 等非 Next.js 框架。其中，React Router v5 的支持在nuqs@2.8.0中被扩展，是适配器体系中较为特殊的一员：官方以 registry item（注册表条目）形式发布，接入方式、兼容性策略与 v6/v7/v8 略有差异。本文以 adapter-react-router-v5.md 为核心，结合 适配器源码 与 适配器内核实现，完整讲解接入步骤与实现原理。

为什么 React Router v5 需要适配器

nuqs 的useQueryState/useQueryStates原本绑定 Next.js 的useSearchParams与路由跳转 API。为了让其它框架也能使用，nuqs 2.x 把「读取当前 URL 的 search params」与「把新状态写回 URL」这两件事抽象成一套统一的接口（AdapterInterface），任何框架只要提供一个适配器就能接入 nuqs。

从 官方适配器文档 可以看到，React Router v6/v7/v8 均有内置适配器（nuqs/adapters/react-router/v6等），而v5 没有内置导出，官方将其作为 registry item 提供：安装后在项目中生成一个本地nuqs-adapter.ts文件，由unstable_createAdapterProvider组装出NuqsAdapter组件。

npx shadcn@latest add https://ui.shadcn.com/r/styles/default/nuqs-adapter-react-router-v5.json

根据 adapter-react-router-v5.json，该条目声明的依赖为：

• react-router-dom@^5（你的路由库）
• nuqs（主体库）

生成的文件目标路径为~/nuqs-adapter.ts，即项目根目录下的nuqs-adapter.ts。

接入步骤：用 NuqsAdapter 包裹 BrowserRouter

官方文档给出的用法非常简洁——用NuqsAdapter把<BrowserRouter>包起来：

// [!code word:NuqsAdapter] import { NuqsAdapter } from './nuqs-adapter' export function ReactRouter() { return ( <NuqsAdapter> <BrowserRouter> <Switch>{/* Your routes here */}</Switch> </BrowserRouter> </NuqsAdapter> ) }

要点说明：

• NuqsAdapter必须位于BrowserRouter外层，这样适配器内部的useHistory()/useLocation()才能拿到路由上下文；
• 之后在任意路由组件中即可照常使用useQueryState、useQueryStates、parseAsString等 nuqs API，状态会写入 URL query string 并保持类型安全；
• 与 React SPA（Vite 等）适配器 的用法一致，适配器本质是一个 React Context Provider，挂载位置越高覆盖范围越广。

适配器源码逐段解析

官方生成的nuqs-adapter.ts完整源码如下（与 e2e 测试工程中的 adapter.ts 完全一致）：

import { type unstable_AdapterInterface as AdapterInterface, unstable_createAdapterProvider as createAdapterProvider, renderQueryString, type unstable_UpdateUrlFunction as UpdateUrlFunction } from 'nuqs/adapters/custom' import { useCallback, useMemo } from 'react' import { useHistory, useLocation } from 'react-router-dom' function useNuqsReactRouterV5Adapter(): AdapterInterface { const history = useHistory() const location = useLocation() const searchParams = useMemo(() => { return new URLSearchParams(location.search) }, [location.search]) const updateUrl = useCallback<UpdateUrlFunction>( (search, options) => { const queryString = renderQueryString(search) if (options.history === 'push') { history.push({ search: queryString, hash: window.location.hash }) } else { history.replace({ search: queryString, hash: window.location.hash }) } if (options.scroll) { window.scrollTo(0, 0) } }, [history.push, history.replace] ) return { searchParams, updateUrl } } export const NuqsAdapter = createAdapterProvider(useNuqsReactRouterV5Adapter)

数据读取：searchParams 的 useMemo 缓存

适配器通过 React Router v5 的useLocation()拿到location.search，再用URLSearchParams包装成searchParams。由于URLSearchParams每次构造都是新对象，这里用useMemo按location.search做缓存——只有当 URL query 真正变化时才重建对象，从而避免因引用不稳定引发下游组件的无谓重渲染（参照 referential-stability.spec.ts 所验证的引用稳定性目标）。

数据写入：updateUrl 的 push / replace 分支

updateUrl是 nuqs 要求适配器实现的核心回调（类型定义见 defs.ts），接收两个参数：

实现逻辑：

1. renderQueryString(search)把URLSearchParams序列化为 query string（不带头部?，实现见 url-encoding.ts）；
2. 依据options.history选择history.push（新增一条历史记录）或history.replace（替换当前记录）；
3. 写入时显式保留window.location.hash，保证导航过程中 URL 的 hash 部分不被冲掉（对应 hash-preservation.spec.ts 验证的场景）；
4. 若options.scroll为true，则window.scrollTo(0, 0)回到页首（对应 scroll.spec.ts）。

注意history.push/history.replace接收的是「描述符对象」而非完整 location——只传search与hash，路径（pathname）沿用当前路由，这是 v5 的典型写法。

组装：createAdapterProvider

createAdapterProvider（从 custom.ts 导出）接收这个自定义 hook，返回一个NuqsAdapterProvider 组件。其内部实现见 context.ts：

export function createAdapterProvider( useAdapter: UseAdapterHook ): AdapterProvider { return ({ children, defaultOptions, processUrlSearchParams, ...props }) => createElement( context.Provider, { ...props, value: { useAdapter, defaultOptions, processUrlSearchParams } }, children ) }

也就是说，NuqsAdapter只是把「如何读取/写入 URL」的 hook 塞进 React Context；useQueryState内部通过useAdapter(watchKeys)（context.ts）取出该 hook 并调用，从而拿到searchParams与updateUrl。若组件树中不存在适配器 Provider，会抛出error(404)，即「未找到适配器」错误（错误码定义见 errors.ts，对应 errors/NUQS-404.md）。

Context 的全局单例：避免多副本冲突

适配器 Context 通过globalWeakSingleton（global-singleton.ts）按 React 实例去重：同一 React 实例内多份 nuqs 副本共享同一个 Context，而不同 React 实例保持隔离。同时在浏览器端会检测window.__NuqsAdapterContext是否被不同 Context 覆盖，若检测到版本不匹配或多 React 实例，会输出error(303)警告（对应 errors/NUQS-303.md）。

适配器还支持哪些 Provider 配置

createAdapterProvider生成的NuqsAdapter除了children，还透传两类配置（类型见 context.ts）：

• defaultOptions：全局默认选项，可取history、shallow、clearOnDefault、scroll、limitUrlUpdates的子集，作为各 hook 未显式传参时的兜底；
• processUrlSearchParams：一个可选的URLSearchParams -> URLSearchParams转换函数，可在 URL 读写前统一加工参数（例如过滤、重命名 key）。

<NuqsAdapter defaultOptions={{ history: 'push', scroll: true }} processUrlSearchParams={params => params} > <BrowserRouter>...</BrowserRouter> </NuqsAdapter>

这些能力对 v5 适配器同样生效，属于适配器体系通用接口。

兼容性：支持的版本范围与生命周期

官方文档在 adapter-react-router-v5.md 中明确了兼容性矩阵：

• 该适配器兼容nuqs@^2.8；
• 对react-router-dom@^5的支持在nuqs@2.8.0中被扩展；
• 该支持大概率会在nuqs@3.0.0中被移除；
• 因此，若你的项目仍依赖 React Router v5，请把依赖锁定到nuqs@^2（例如"nuqs": "^2.8.0"），避免未来大版本升级导致适配器失效。

对比之下，React Router v6 已进入生命周期尾声（官方文档标注其适配器同样将在 nuqs@3.0.0 移除，且泛化导入nuqs/adapters/react-router已标记废弃，v7/v8 才是当前演进方向，详见 adapters.mdx）。v5 适配器之所以走 registry 而非内置导出，正是因为其作为「遗留版本支持」的定位：代码量小、维护成本低、且生命周期明确受限。

使用限制与注意事项

从源码与文档可以确认以下边界：

• 仅支持BrowserRouter。官方在 adapters.mdx 中明确：只有BrowserRouter受支持，HashRouter未来可能支持（对应 issue #810），MemoryRouter无支持计划。如果你的 v5 应用使用HashRouter或MemoryRouter，应自行实现自定义适配器。
• shallow: false无实际效果。与无服务器的 React SPA 场景相同（见 adapters.mdx 的说明），纯前端路由环境下不存在服务端渲染回调，shallow选项没有可作用的对象。
• 源码中仍留有 TODO。在 e2e 测试工程中的 adapter.ts 中可以看到// todo: Shallow (using the History API)与// todo: Key isolation注释，表明 key isolation（URL key 隔离，见 key-isolation.ts）等高级特性尚未在 v5 适配器中落地，这也是将其定位为扩展支持而非一等公民的原因之一。

如何在本地验证适配器行为

仓库的 e2e/react-router/v5 目录提供了完整的 Playwright 测试工程，可用于对照验证：

• main.tsx 展示了挂载入口：StrictMode下渲染ReactRouter组件；
• react-router.tsx 与 layout.tsx 展示NuqsAdapter与路由的组合方式；
• adapter.ts 即为适配器实现（与 registry 发布的 source 一致）；
• specs 下的测试用例（如 repro-1501.spec.ts、repro-1506.spec.ts）覆盖了与该路由版本相关的回归场景。

如果你需要为其他 React Router 变体（v6/v7/v8）或完全没有路由的 React SPA 接入 nuqs，可参考 适配器总览文档 中对应的内置适配器，或基于 custom.ts 暴露的 unstable API 编写自己的适配器——v5 适配器本身就是这样一个「自定义适配器」的官方范例。

总结

在 React Router v5 项目中接入 nuqs 只需三步：安装react-router-dom@^5与nuqs@^2、通过 registry 生成nuqs-adapter.ts、用导出的NuqsAdapter包裹BrowserRouter。其背后是 nuqs 统一的适配器抽象：useLocation+useMemo负责读取，history.push/replace+renderQueryString负责写入，createAdapterProvider负责注入 React Context。理解这份适配器源码，你既能快速排查接入问题，也能把它当作编写任意自定义路由适配器的模板。最后务必记住：该支持的生命周期绑定在nuqs@^2，升级到 3.x 前请先迁移 React Router 版本。

• 前端
• 状态管理