URL 状态与状态机

• storage 事件跨标签同步
• navigator.storage.estimate 估算配额
• 配额预警与持久化策略

storage 事件在其他标签页修改 localStorage 时触发，用于跨标签同步数据。navigator.storage.estimate() 返回 { usage, quota }，估算当前已用与总配额，用于配额预警。工程价值：在接近配额时预警用户、清理缓存或引导清理，避免写入失败。结合持久化（navigator.storage.persist()）可申请持久存储。工程实践：启动时估算配额，接近阈值时提示或降级。

storage 事件解决"跨标签同步"，estimate 解决"配额监控"。两者结合让持久化更可靠，避免因配额不足导致数据丢失或写入失败。

• loader 的数据预取
• 与 TanStack Query 的集成
• 缓存与去重

TanStack Router 提供 loader 在路由导航前预取数据，与 TanStack Query 深度集成，loader 中可 prefetchQuery 写入缓存，导航后组件直接命中。它支持并发加载、数据去重、缓存复用，避免重复请求。工程价值：路由层承担数据获取编排，页面组件只消费数据，提升导航性能与数据一致性。配合 type-safe 路由，数据获取类型安全。

TanStack Router 把"数据获取"纳入路由生命周期。loader 预取 + Query 缓存，让导航时数据就绪，减少等待，是路由与数据缓存的现代协作。

• 类型推导的路径与参数
• URL 状态与路由参数的类型安全
• 编译期校验

TanStack Router 内置 type-safe 路由：路径、search 参数、loader 数据类型在编译期推导，链接跳转、参数读取都有类型提示，避免拼错路径或参数类型错误。它与 URL 状态协作时，searchParams 通过 schema（如 Zod）校验，类型安全地同步到组件。工程价值：减少手写字符串路由与类型断言，提升重构安全性，URL 状态与组件类型一致。

type-safe 路由把"URL 字符串"变成"类型安全 API"。编译期校验路径与参数，减少运行时错误，提升开发体验与可维护性。

• useSearchParams 读取/更新 URL 参数
• URL 作为请求状态
• 与缓存 key 的协作

useSearchParams 让组件读取和更新 URL 查询参数，URL 成为"可分享、可刷新保留"的请求状态。数据获取时，把 URL 参数作为 queryKey 的一部分，参数变化触发重新获取或命中缓存。工程价值：页面状态（筛选、分页、搜索）可分享、可后退、可刷新保留，与缓存 key 对齐实现数据一致性。相比存 store，URL 状态天然持久且可回溯。

URL 状态的价值是"持久 + 可分享 + 可回溯"。useSearchParams 提供声明式读写，与 queryKey 协作让"URL 即请求状态"。

• proxy 响应式状态
• 跨标签同步手段
• 多窗口一致性

Valtio 本身是单标签内的响应式状态，跨标签/跨窗口需借助 storage 事件、BroadcastChannel 或 storage 中间件。把 proxy 状态与 storage 同步，其他标签页修改时触发更新，实现多窗口状态一致。工程价值：结合 Valtio 的响应式更新与跨标签广播，让多个窗口/标签共享同一状态（如登录态、购物车），提升一致性。取舍：需处理同步冲突与存储容量。

Valtio 的响应式是"单标签内"，跨标签要叠加同步机制。proxy 的订阅模型可与 storage/BroadcastChannel 结合，实现多窗口状态同步。

• query string 与 hash 的用途
• 可分享/可回溯的工程价值
• 何时不适合用 URL 状态

URL 作为状态通过 query string（?key=value）和 hash（#/path 或 #key=value）承载。query string 适合可分享、可回溯的请求状态（筛选、分页、搜索）；hash 适合不需要服务端处理的片段状态（如锚点）。工程价值：状态可分享、刷新保留、后退恢复。边界：不宜承载超大、敏感、高频或非语义的状态；敏感数据不应放 URL（易泄露）。需权衡"可分享性"与"状态的本地性"。

URL 状态的边界是"是否值得作为 URL 的一部分"。可分享、可回溯、语义化时适合；否则存 store 更合适。URL 仅适合简单、可序列化、非敏感的状态。

• nuqs 的 useQueryState 抽象
• 类型安全与序列化解析
• 与 useSearchParams 的对比

nuqs 提供 useQueryState 等 Hook，把 URL 参数当作 React 状态读写，封装了序列化解析、类型转换、防抖等。相比原生 useSearchParams，nuqs 提供类型安全、更简洁的"状态即 URL"心智模型，并适配 Next.js 的服务端组件与客户端。现代实践：用 parseAsInteger/parseAsString 等解析器声明参数类型，参数变化自动同步 URL 并触发。工程价值：减少手写 URL 序列化/解析逻辑，提升类型安全与可维护性。

nuqs 是"URL 状态库"的现代代表。它把 URL 参数成首等状态，封装解析与同步，让 URL 状态管理更安全、更简洁。

• TanStack Router 的 type-safe search 状态
• React Router 的 useSearchParams
• 类型安全与能力的取舍

TanStack Router 内置 type-safe 的 URL 状态管理：search 参数通过 schema（validateSearch）校验，类型推导到组件，提供 useSearch/navigate 等类型安全 API。React Router 用 useSearchParams 读取/更新 URL，简单但类型较弱、需手动校验。取舍：TanStack Router 提供更强的类型安全与校验，但引入新路由库与学习成本；React Router 成熟、生态大、简单直接。选型取决于对类型安全与 URL 状态复杂度的需求。

取舍核心是"类型安全与复杂度"。TanStack Router 把 URL 状态类型化到极致，React Router 更简单通用。复杂 URL 状态需求选 TanStack，简单场景 React Router 足够。

• 复杂对象的序列化/反序列化
• 自定义编解码器
• 编码长度与可读性

URL 只能承载字符串，复杂对象（数组、嵌套、日期）需自定义编解码器序列化。可用 JSON.stringify 后 encodeURIComponent，或分字段编码；数组用逗号分隔或重复参数。自定义编解码器封装在单一函数，负责存取与解析，保证一致性。工程注意：编码长度、可读性、特殊字符转义、版本兼容。取舍：复杂对象编码可读性差、长度大，需平衡，必要时用压缩（如 gzip+base64）。

序列化是"URL 状态"与"内存对象"的桥梁。自定义编解码器集中处理序列化，保证存取一致，是复杂 URL 状态的基础。

• URL 状态对 SSR/SEO 的友好
• 相较 store 的对比
• 内容与状态的可索引性

URL 状态对 SSR 与 SEO 友好：服务端可直接读取 URL 参数渲染对应内容，爬虫可索引不同 URL 对应的页面。相较 store（内存状态），URL 状态可被服务端读取、可分享、可被搜索引擎索引。取舍：需要 SEO 与可分享的内容相关状态应放 URL；纯 UI 交互状态（如弹窗、临时选择）放 store 更合适。工程上把"影响内容/SEO"的状态放 URL，把"交互瞬时"状态放 store。

URL 状态是"服务端可读、可索引"的。SEO 与可分享内容应放 URL，纯交互状态放 store，这是状态归属的关键取舍。

• storage 事件的机制与限制
• BroadcastChannel 的双向消息
• 多窗口协作的选型

storage 事件在 localStorage 变化时触发，但只在"其他标签页"触发（本页不触发），且只能传递存储的值，本质是"写存储-被监听"的间接通信。BroadcastChannel 允许任意标签页之间直接双向发送消息，无需存储，适合实时事件广播。取舍：storage 事件适合"与 localStorage 同步"的场景，BroadcastChannel 适合"实时消息/命令"场景；BroadcastChannel 更灵活、无存储污染，但需考虑数据持久化。多窗口协作（如登录态、购物车）常两者结合。

storage 事件是"通过存储间接同步"，BroadcastChannel 是"直接消息通道"。实时性要求高、需双向通信选 BroadcastChannel；需要持久化同步选 storage 事件。

• v5 的 actor 模型
• createMachine/setup 的现代 API
• 类型安全与组合性改进

XState v5 引入 actor 模型，每个状态机是 actor，用 createActor 启动，通过 send 发送事件、subscribe 订阅快照。v5 用 createMachine/setup 定义，setup 用于声明 context、guards、actors 等类型，实现更强的类型推断。相较 v4，v5 改进：更完整的类型安全（事件、context、状态推导）、更好的组合性（actor 嵌套、spawn）、统一的 API。工程价值：状态机可组合、可测试、类型安全。

v5 的 actor 模型把状态机作为一等公民，setup 提供类型化的声明，提升类型安全与组合性。这是状态机库现代化的重要演进。

• Statecharts 的层次/并行/守卫
• 可视化与可测试性
• 复杂流程组合

Statecharts 是状态机的扩展，支持层次状态、并行状态、守卫、动作、事件，适合建模多步骤表单/支付流程。相较 useReducer：Statecharts 以声明式状态图描述流程，可可视化（Stately Inspector）、可测试（给定事件断言状态）；复杂状态组合（并行、嵌套、历史）用 useReducer 手写极易出错。工程价值：支付流程的"待支付-支付中-成功/失败"等状态用状态机建模，分支清晰、可施加守卫、可追踪。

Statecharts 的优势是"显式建模 + 可测试 + 可组合"。多步骤流程的复杂分支用状态图表达，比手写 reducer 更清晰、更可靠。

• headless 组件与状态机
• UI 解耦的 design philosophy
• Ark UI 生态

Zag.js 把组件的交互逻辑（状态机）与 UI 解耦，提供无样式（headless）的组件状态机，UI 库（堆叠成样式组件）负责外观。它用状态机管理交互状态，保证逻辑一致、可测试、可复用。Ark UI 基于 Zag.js 生态，提供可访问、可定制的组件库。工程价值：交互逻辑与样式解耦，一套逻辑适配多种 UI 风格；状态机保证交互可预测、可测试；提升组件库的可维护性与可访问性。

headless 模式的哲学是"逻辑与 UI 分离"。Zag.js 用状态机承载交互逻辑，Ark UI 提供落地组件，兼顾一致性与可定制性。

• 层次状态的嵌套
• 并行状态的独立进行
• 复杂交互建模

层级状态（Hierarchical）允许子状态嵌套在父状态内，父状态定义了子状态的公共上下文与行为，如编辑器的"编辑中/保存中/已保存"子状态。并行状态（Parallel）允许多个独立区域同时处于各自状态，如向导中"内容校验"与"进度显示"并行进行。工程价值：复杂交互（编辑器、向导）用层级/并行状态清晰建模，避免扁平状态爆炸，提升可读性与可维护性。

层级状态浓缩公共行为，并行状态表达独立维度。两者是 Statecharts 处理复杂交互的核心结构，让状态模型更接近真实世界。

• guards 的条件分支
• actions 与 entry/exit action
• context 更新与可测试性

XState 中守卫（guards）在转移时判断条件（如 cond），决定是否接受该事件；动作（actions）执行副作用（如调 API、日志），entry/exit action 在进入/离开状态时执行；context 是状态机携带的数据，通过 assign 更新。分工：guards 决定"走哪条分支"，actions 执行"副作用"，context 更新"数据变更"。可测试性：guards 是纯函数可单测，actions 可注入 mock，状态转移可断言。组织上把条件、副作用、数据分离，便于测试与复用。

分工是"条件判分流、动作管副作用、assign 管数据"。清晰分离让状态机可测试、可预测，是状态机工程化的关键。

• useQueryState 的声明式读写
• 类型安全与解析器
• URL 与 state 同步

nuqs 的 useQueryState 把 URL 参数映射为 React state，读写时自动同步 URL。通过解析器（parseAsString/parseAsInteger/parseAsArrayOf 等）声明参数类型，实现类型安全：读取得到类型化值，写入时自动序列化。工程价值：URL 状态与组件 state 无缝同步，类型安全减少序列化错误，参数变化自动反映到 URL 并可分享/后退。相比手写 useSearchParams，nuqs 更简洁、类型安全。

nuqs 把"URL 参数"提升为"类型安全的 state"。解析器声明类型，读写同步 URL，让 URL 状态管理声明式、安全。

• URLSearchParams 的 API
• 查询参数的读写与序列化
• 与 React 状态结合

URLSearchParams 提供查询参数的解析与操作 API（get/set/append/delete/toString），用于读写 URL 查询字符串。状态管理中，用 URLSearchParams 把查询参数序列化/反序列化，结合 history.pushState 或 React Router 的 useSearchParams 更新 URL。工程价值：统一查询参数处理，避免手写字符串拼接；配合 URL 状态，让查询参数可分享、可后退。注意值都是字符串，复杂类型需转换。

URLSearchParams 是"查询参数的标准工具"。它规范读写，结合路由 API 实现查询参数的声明式状态管理。

• 三者容量与生命周期差异
• 同步/异步差异
• 持久化选型

localStorage 容量约 5MB、同步、跨标签共享、会话间持久；sessionStorage 容量类似、同步、按标签页隔离、关闭标签清除；IndexedDB 容量大（数百 MB-GB）、异步、跨标签共享、可存结构化数据。选型：小数据、同步、跨会话用 localStorage；会话级临时数据用 sessionStorage；大数据、复杂结构用 IndexedDB。同步差异：localStorage 同步读写，IndexedDB 异步，配合回调/Promise。工程价值：按数据规模与生命周期选择合适存储。

三者差异在"容量、生命周期、同步性"。按需选型：小且持久用 localStorage，临时用 sessionStorage，大且复杂用 IndexedDB。

• BroadcastChannel 的双向消息
• StorageEvent 的存储驱动
• SharedWorker 的共享上下文

BroadcastChannel 提供标签页间直接双向消息，简单高效，适合实时事件；StorageEvent 在 localStorage 变化时触发，间接通过存储同步，适合与持久化结合；SharedWorker 是共享的 worker 上下文，可承载计算与状态，适合复杂共享逻辑，但实现复杂、生命周期管理难。取舍：实时通信选 BroadcastChannel；持久化同步选 StorageEvent；需共享计算/复杂状态选 SharedWorker。工程上常 BroadcastChannel + StorageEvent 组合。

三种方案角度不同：BroadcastChannel 是消息通道，StorageEvent 是存储驱动，SharedWorker 是共享运行时。按实时性、持久性、复杂度选型。

• 路由定义与数据加载
• 类型安全与 URL 状态
• 选型考虑

React Router 是成熟、生态大的路由库，支持声明式路由、loader（data API）、嵌套路由，与 React 深度集成。TanStack Router 是较新的路由库，强调 type-safe 路由、内置 search 状态管理、与 TanStack Query 集成。取舍：React Router 成熟稳定、学习成本低、生态丰富；TanStack Router 类型安全更强、URL 状态能力更完善，但较新、需适应。工程选型取决于对类型安全、URL 状态复杂度与生态成熟度的需求。

两个路由库在"成熟度"与"类型安全/URL 状态"上取舍。React Router 稳妥通用，TanStack Router 面向类型安全与高级 URL 状态。

• BroadcastChannel 的创建与消息
• 跨 tab 状态同步
• 与 storage 方案的对比

BroadcastChannel 创建命名通道，postMessage 向所有监听同通道的标签页广播消息，onmessage 接收。多标签跨 tab 状态同步时，一个标签页更新状态后广播，其他标签页监听并更新，实现实时一致性。工程价值：实时性优于 storage 事件（无存储写入）、支持双向消息、无存储污染。适合登录态、购物车、设置等跨标签同步。注意消息需可序列化、需处理异常。

BroadcastChannel 是"跨标签消息总线"。相比 storage 事件需写存储，BroadcastChannel 直接广播，实时且干净，是多标签同步的现代方案。

• persist 中间件的存储抽象
• 自定义 storage 为 IndexedDB
• 持久化与 rehydrate

Zustand 的 persist 中间件把 store 状态持久化，默认用 localStorage，但可通过 createJSONStorage 自定义 storage。idb-keyval 提供基于 IndexedDB 的简单 key-value 存储，可实现成 persist 的 storage 适配器，获得更大容量与异步读写。协作：配置 persist 时用 idb-keyval 作为 storage，支持大状态持久化；rehydrate 时从 IndexedDB 恢复。工程价值：结合 IndexedDB 容量与 persist 的易用性，持久化大状态。

persist 的 storage 是可插拔的。用 idb-keyval 替换默认 localStorage，让持久化突破 5MB 限制，适合大状态。

• OPFS 的文件系统能力
• SQLite（sql.js）的 SQL 查询
• 大型客户端数据的选型

OPFS（Origin Private File System）提供高性能的私有文件系统，适合大文件、二进制数据的读写，异步、容量大。SQLite（sql.js）是 WASM 版 SQLite，可在浏览器中运行 SQL，支持复杂查询、索引、事务，适合关系型数据。取舍：需要 SQL 查询、复杂关系、索引时用 SQLite；需要高性能文件存储、二进制、大文件时用 OPFS。工程价值：大型客户端表（如离线数据、复杂查询）用 SQLite，大文件/二进制用 OPFS，均可突破 localStorage 限制。

OPFS 是"文件存储"，SQLite 是"数据库"。选型看数据形态：结构化关系数据用 SQL 查询选 SQLite，大文件/二进制选 OPFS。

• persist 中间件的配置
• localStorage 持久化与 rehydrate
• 版本与迁移

persist 中间件把 Zustand store 的状态持久化到 localStorage，默认用 JSON 序列化，初始化时自动 rehydrate 恢复。工程应用：配置 persist 指定存储名与部分持久化（partialize），配合 version 处理版本迁移，onRehydrateStorage 处理恢复后的逻辑。价值：刷新后状态保留，无需重复初始化。注意：持久化的数据需验证有效性，避免旧数据损坏；敏感数据不宜持久化。

persist 是"状态持久化"的便捷封装。localStorage 同步、持久、容量小，适合小状态；配置 version 与 partialize 保证迁移安全。

• persistReducer/persistStore
• 状态序列化与 whitelist/blacklist
• 版本迁移（migrations）

Redux Persist 用 persistReducer 包裹 reducer，persistStore 启动持久化，把状态序列化到 storage。通过 whitelist/blacklist 选择持久化的切片，配置 version 与 migrate 函数处理版本迁移：旧版本状态可转换到新 schema。工程应用：持久化登录态、偏好等，版本升级时迁移旧状态。价值：状态持久、可迁移，避免升级后状态损坏。

Redux Persist 的迁移机制是"版本化状态升级"。whitelist 控制持久化范围，migrate 按版本转换状态，保证 schema 演进后状态兼容。

• atomWithStorage 的持久化原子
• 自动读写 storage
• 跨标签同步

atomWithStorage 创建一个持久化原子，自动把值写入 localStorage/sessionStorage，初始化时读取恢复，并支持跨标签同步（监听 storage 事件）。它像普通 atom 一样用 useAtom 使用，持久化逻辑透明。工程价值：声明式持久化，无需手写 storage 读写；支持按 key 隔离、可配置存储；跨标签同步保持一致性。

atomWithStorage 是"原子级持久化"。它把 storage 读写封装进原子，与 Jotai 的原子模型无缝结合，持久化透明。

• 版本号与状态 schema
• 迁移函数与降级
• 大型应用的迁移策略

状态持久化需版本管理：存储带版本号，schema 变化时通过迁移函数把旧版本状态转换到新版本。策略：定义版本号、迁移函数链、处理缺失/损坏数据（回退默认值）。工程边界：迁移应幂等、可测试；兼容旧版本到新版本；对无法迁移的数据降级为默认状态。价值：大型应用长期演进中，持久化状态不因 schema 变化而损坏。

版本管理是"持久化状态的 schema 演进"。迁移函数保证旧数据可用，幂等与降级处理异常，是长期维护的关键。

• IndexedDB 的容量与异步
• Dexie.js/idb 的封装
• 大量数据持久化

IndexedDB 提供浏览器内的大容量、异步、结构化数据存储，适合大量数据持久化。原生 API 冗长，Dexie.js 提供更友好的 Promise 封装与查询，idb 提供轻量的 Promise 化封装。工程应用：存储离线数据、缓存大对象、Session 数据等。价值：突破 localStorage 容量限制，支持索引与事务，适合大数据量场景。

IndexedDB 是"大数据持久化的标准"。Dexie.js/idb 简化其 API，让大量数据存储更易用，是前端离线与大数据存储的基础。

• Cookie 的容量与自动携带
• 服务端共享与会话
• Cookie 的安全与取舍

Cookie 随请求自动发给服务端，适合服务端共享的会话状态（登录态、偏好）。取舍：容量小（约 4KB）、每个请求都携带（影响带宽）、易受 XSS/CSRF 风险（需 HttpOnly/Secure/SameSite）。持久化方面，Cookie 适合小状态且服务端需要；客户端独享的大状态用 localStorage/IndexedDB 更合适。工程价值：会话与鉴权用 Cookie（HttpOnly 安全），非敏感 UI 状态用客户端存储。

Cookie 的优势是"服务端自动共享"，劣势是"容量小、带宽、安全"。选型看是否需服务端读取与安全等级。

• URL 分享链接的可复现性
• 后退/前进的历史恢复
• URL 状态与浏览器历史

URL 状态承载页面状态（筛选、分页、搜索），分享链接时接收方可复现相同页面；浏览器后退/前进时，URL 变化触发状态恢复，实现历史导航。工程价值：URL 状态天然可分享（复制链接即复现）与可回溯（后退/前进恢复状态），无需额外状态持久化。配合 history API 或路由库，URL 变化驱动状态更新。取舍：仅适合可分享、可序列化的状态。

URL 状态与浏览器历史天然绑定。分享与后退/前进是 URL 状态的独特价值，存 store 无法实现。

• URL 状态的分享链接能力
• SSR 可读性
• 与 Redux/Zustand 的对比

URL 状态作为 React 状态管理，相比 Redux/Zustand 的独特价值：一是分享链接——URL 承载状态，复制链接即可复现；二是 SSR——服务端可读取 URL 参数渲染页面，利于 SEO。Redux/Zustand 是内存状态，无法分享、无法被服务端直接读取。取舍：可分享、需 SSR/SEO 的状态用 URL 状态；纯交互、频繁更新的状态用 Redux/Zustand。工程上可结合：URL 状态用于"可分享的请求状态"，store 用于"本地交互状态"。

URL 状态的价值是"可分享 + 服务端可读"，Redux/Zustand 是"内存高效"。按状态特性分流，是工程实践的关键。

• 用 Zod 解析 searchParams
• React Router loader 的类型安全
• 参数校验与类型推导

把 searchParams 用 Zod schema 解析，校验参数类型与格式，失败时提供默认值或错误。React Router data API 的 loader 可在服务端/客户端读取 URL 参数，用 Zod 解析后返回类型化数据。协作：loader 中用 Zod 解析 searchParams，得到类型安全的参数，传给组件渲染；类型推导贯穿 loader 返回数据。工程价值：参数校验、类型安全、错误处理统一，减少运行时类型错误。

Zod schema 化把"URL 参数"变成"类型安全+校验"。与 React Router loader 结合，URL 参数在取数前就被校验与推导类型。

• pushState/replaceState 更新 URL
• 深链接与前进后退
• 与路由库的取舍

pushState 新增历史记录、replaceState 替换当前记录，均不刷新页面，用于 SPA 更新 URL。工程价值：支持深链接（直接访问某 URL 渲染对应状态）与后退恢复（历史栈驱动状态变化）。取舍：手写 History API 需自己处理 popstate、状态同步；路由库（React Router/TanStack Router）封装了 history 管理，提供更完善的 URL 状态与导航。大型 SPA 建议用路由库，简单场景可手写。

History API 是"URL 状态与历史"的原生基础。深链接与后退需要历史栈管理，路由库封装了这些，避免手写错误。

• useSearch 读取类型化参数
• validateSearch 校验 schema
• 类型安全与错误处理

TanStack Router 的 validateSearch 用 schema（如 Zod）校验 URL search 参数，校验通过后推导类型，useSearch 读取类型安全的参数。参数无效时返回默认值或抛错。工程价值：URL 参数在进入组件前已验证与类型化，避免运行时类型错误；useSearch 提供类型推导的读取；配合导航 API 保证参数一致性。是现代 URL 状态 type-safe 管理的核心。

validateSearch 把"URL 参数校验"前置到路由层。useSearch 消费类型化的结果，让 URL 状态全程类型安全。

• sessionStorage 的标签隔离与生命周期
• 表单草稿的临时保存
• 与 localStorage 的对比

sessionStorage 按标签页隔离，数据在标签页关闭或浏览器关闭后清除，适合"会话级临时数据"。表单草稿应用：保存当前会话的填写内容，刷新或误导航后恢复，但多标签不串数据、关闭后自然清除。工程价值：临时草稿不污染其他标签、不持久残留，保护隐私。相比 localStorage 跨会话持久，sessionStorage 更适合临时性状态。

sessionStorage 的价值是"会话隔离 + 自动清除"。表单草稿用它保存临时进度，刷新恢复且不跨会话残留。

• IndexedDB 作为持久化后端
• Redux Persist/Zustand persist 的适配
• 大型状态持久化

IndexedDB 可作为 Redux Persist 和 Zustand persist 的持久化后端，替换 localStorage 以支持更大容量的状态。Redux Persist 通过自定义 storage（配合 idb 的 Promise 封装）接入 IndexedDB；Zustand persist 通过 createJSONStorage 自定义 storage。工程价值：大型状态（大量实体、缓存、列表）持久化突破 5MB 限制，异步写入不阻塞主线程。取舍：IndexedDB 异步、实现稍复杂，但容量与性能更优。

大型状态持久化选中 IndexedDB 是"容量与性能"的考量。两者都支持自定义 storage 适配，接入 IndexedDB 后大状态可持久化。

• SSR 与客户端 URL 状态差异
• hydration mismatch 原因
• 处理边界

SSR 注水不一致指服务端渲染的 HTML 与客户端首次渲染不一致（hydration mismatch）。URL 状态相关：服务端读取 URL 参数渲染，客户端重新读取时可能因 URL 解析、默认值、时间/随机值不同导致不一致；或客户端在 hydration 前修改了 URL。处理边界：URL 状态在服务端与客户端应读取一致；对非确定性部分（如当前时间、storage）用客户端渲染或延迟；必要时用 useEffect 在 hydration 后更新。工程价值：避免 hydration mismatch 导致的 DOM 错误与闪烁。

hydration match 要求"服务端与客户端首帧一致"。URL 状态应保证两端一致，非确定性内容延后到客户端处理。

• 各解析器的用法
• 类型推导
• 解析边界与默认值

nuqs 的 parseAsString/parseAsInteger/parseAsArrayOf 等解析器声明 URL 参数类型：parseAsString 解析字符串、parseAsInteger 解析整数、parseAsArrayOf 解析数组（可指定元素解析器）。类型推导：解析器返回类型可推导到 useQueryState 的值类型。边界：解析失败时返回默认值或 null；数组需处理分隔符（逗号/重复参数）；类型转换的边界（如溢出、非法值）需处理。工程实践：声明解析器与默认值，处理解析失败。

解析器是"URL 参数的类型契约"。它们声明类型并推导，但需处理解析失败与边界，保证健壮性。

• URL 参数作为 queryKey 的一部分
• 缓存键与 URL 一致性
• 边界与同步

URL 状态与 queryKey 协作：把 URL 参数（筛选、分页、搜索）作为 queryKey 的一部分，使 URL 变化对应不同的缓存键，命中或创建对应缓存。一致性边界：URL 参数变化时 queryKey 变化，触发新查询或复用缓存；需保证 URL 参数的序列化与 queryKey 一致，避免"URL 变了但缓存键不变"导致缓存错乱。工程价值：URL 即请求状态，缓存键与 URL 对齐，实现数据一致与可分享。

一致性边界是"URL 参数与 queryKey 必须一一对应"。参数归一化（排序、序列化）保证同一 URL 命中同一缓存键。

• form action 提交后的重定向
• 保留搜索条件
• URL 状态与表单协作

Remix/Next.js 中，表单提交后常重定向到处理后的页面，重定向时保留搜索条件（筛选、分页）让用户回到原上下文。工程价值：URL 状态承载搜索条件，action 处理后可重定向到"保留参数的 URL"，实现提交后不丢失筛选状态。实现上把搜索条件作为 URL 参数，重定向时携带。相比 store 状态，URL 状态可分享、可回退，且服务端可读，利于表单提交后的状态保持。

保留搜索条件的关键是"URL 参数随重定向携带"。URL 状态让表单提交后上下文可恢复，是 Remix/Next.js 的现代实践。

• Stately Inspector 可视化
• XState typegen 的类型生成
• 工程协作边界

XState 提供 Stately Inspector 可视化状态机，实时展示状态、事件、转移，便于调试；VSCode 插件提供状态图编辑与类型生成。typegen 从状态机自动生成类型（事件、状态、context），提升类型安全。工程协作边界：可视化调试降低理解成本，typegen 让状态机类型安全，但需 keep 状态机与 typegen 同步，避免不一致。价值：团队协作时状态机可共享、可审查、可测试。

可视化与 typegen 是"可观测 + 类型安全"。它们提升协作效率，但需维护状态机与生成类型的同步，边缘需注意。

• 事件溯源的事件记录
• 状态机的状态重放
• 时间旅行调试

事件溯源把状态变更记录为事件序列，状态由事件重放得出。状态机与事件溯源结合：状态机的转移由事件驱动，事件序列可重放，任意时间点可重算状态，实现时间旅行调试。工程模式：记录状态机接收的事件，重放事件序列可恢复历史状态、回退/前进。价值：状态可追溯、可复现、可调试，适合审计与复杂流程。取舍：事件存储成本与重放复杂度。

事件溯源是"状态=事件序列的投影"。状态机天然事件驱动，两者结合让状态可重放，是时间旅行调试的基础。

• invoke 启动异步 actor
• promise actor 的完成/错误
• 重试与轮询

XState 的 invoke 启动异步 actor（promise、callback、actor），promise actor 执行异步任务，完成触发 onDone、错误触发 onError。错误处理：onError 转移状态处理失败，可重试（重发事件或回到初始状态）。轮询：用 while 循环或递归 invoke 周期性调用。工程价值：异步流程状态化，错误处理显式，重试策略可配置，配合 guards 控制重试条件。

invoke 把异步流程纳入状态机。onDone/onError 处理成功/失败，重试与轮询通过状态转移表达，让异步流程可预测、可测试。

• history.state 的存储能力
• 临时 UI 状态的存储
• 使用边界与取舍

window.history.state 是当前历史记录的状态对象，可存储任意数据，pushState/replaceState 时携带。用它存储临时 UI 状态（Modal 打开、表单填写）可让后退/前进恢复这些状态。取舍：优点是状态与历史绑定、可后退恢复；缺点是不持久（页面刷新丢失）、需手动管理、不适合大状态。工程上：适合"与导航相关的少量 UI 状态"，复杂或频繁状态用 store 更合适。

history.state 的价值是"与历史记录绑定"。它让临时 UI 状态可随后退/前进恢复，但非持久、手动管理，是边界。

• URL 状态对 SEO 的影响
• 爬虫可索引性
• Open Graph 分享卡片

URL 状态影响 SEO：内容相关状态放 URL 可被爬虫索引，不同 URL 对应不同页面；纯交互状态放 URL 可能造成重复内容或爬虫困惑。社交分享：Open Graph 标签（og:title/og:image）随 URL 渲染分享卡片，URL 状态决定分享的内容。工程价值：把影响内容/分享的状态放 URL，配合 SSR 渲染对应 OG 标签，提升 SEO 与分享体验。取舍：避免无意义 URL 参数污染索引。

URL 状态是"内容可寻址"的基础。影响内容与分享的状态放 URL，配合 SSR 与 OG 标签，是 SEO 与分享的关键。

• useSyncExternalStore 订阅外部状态
• popstate 事件监听
• 同步 URL 状态到 React

useSyncExternalStore 可订阅外部状态（window.location、popstate），subscribe 监听事件、getSnapshot 读取当前值。URL 状态同步：订阅 popstate 事件，getSnapshot 返回 location 的 URL 参数，URL 变化时组件自动更新。React 19 协作：useSyncExternalStore 保证并发渲染下外部状态读取一致，避免 tearing。工程价值：把 URL 状态作为外部 store 接入 React，无需 Context，实现 URL 驱动的响应式更新。

useSyncExternalStore 是"外部状态接入 React 的官方桥"。订阅 popstate 让 URL 变化触发组件更新，与 React 并发特性兼容。

• Jotai 原子状态
• 跨标签同步手段
• 与 storage/BroadcastChannel 结合

Jotai 本身是单标签内的原子状态，跨标签/跨窗口需借助 storage 或 BroadcastChannel。atomWithStorage 支持跨标签同步（监听 storage 事件），也可用自定义订阅配合 BroadcastChannel。工程价值：用 Jotai 的原子模型管理状态，叠加跨标签同步，实现多窗口一致（登录态、设置）。取舍：需处理同步冲突与序列化，Jotai 的原子化让同步目标更清晰。

Jotai 提供"原子级状态"，跨标签需叠加同步机制。atomWithStorage 的 storage 同步或 BroadcastChannel 广播实现多窗口一致。

• Zustand store 与 URL 同步
• 路由参数映射到 store
• 双向同步边界

Zustand 与 URL 状态协作：把 URL 参数同步到 store，或在 store 变化时更新 URL。常见做法：路由变化时把 searchParams 写入 store；store 变化时用 history/replaceState 更新 URL。双向同步需注意避免循环（URL 触发 store 更新，store 又触发 URL 更新）。工程价值：store 管理交互状态，URL 管理可分享状态，两者结合实现"可分享 + 高效"。取舍：URL 状态适合可分享部分，复杂交互状态放 store。

协作是"store 与 URL 的双向映射"。需控制同步方向避免循环，合理划分"可分享的 URL 状态"与"交互 store 状态"。

• 以状态机为模型
• 路径生成与覆盖
• 自动化测试价值

@xstate/test 基于模型测试：以状态机为被测模型，自动生成覆盖所有状态/转移的测试路径，执行路径并断言状态。它根据状态图生成路径序列，覆盖关键分支与状态。工程价值：自动化生成高覆盖测试，减少手写测试用例；状态机本身即测试模型，可测试性高；路径覆盖提升置信度。取舍：需维护状态机模型，复杂状态图路径可能爆炸，需裁剪。

模型测试是"以状态机驱动测试生成"。状态图提供路径，@xstate/test 自动生成覆盖路径，是状态机可测试性的延伸。

• URL 长度边界
• 压缩序列化（gzip+base64）
• 超长参数回退策略

URL 有长度限制（浏览器/服务器不同，通常 2KB-8KB），超长参数会被截断或报错。分享链接场景可用压缩序列化（如把对象 JSON 后 gzip 压缩再 base64）减小长度，但可读性差、编码复杂。取舍：压缩序列化节省长度但牺牲可读与调试；可读性好则长度大。回退策略：超长参数不全部放 URL，改用短 ID 关联服务端/存储，URL 只放短引用；或分段、摘要。工程价值：平衡分享链接的可读性与长度，超长时回退到引用方式。

URL 长度是硬边界。压缩序列化是"长度换可读性"，超长时回退到"短引用 + 服务端存储"是更可扩展的方案。