React URL Hash 状态同步实战：从朴素 useHash 到生产级实现

做前端这么多年我一直觉得URL里的hash是被低估得最狠的一个API。大多数人只在面试时背过它和history的区别真到业务里需要把一个Tab状态、一坨筛选条件、一个弹窗开关塞进地址栏并且和React状态保持同步时能一次写对的人并不多。这也是我单独把useHash拎出来写一篇的原因它看起来不过就是location.hash加一个监听事件但想写得经得起真实项目折腾里面至少有五六个能让人栽跟头的细节。这篇文章我会从使用场景讲起带你看朴素实现的坑再给出一个生产级的 useHash 实现顺带把我踩过的问题和排查思路整理成速查表。不管你是刚开始写React Hook的小白还是已经在项目里维护过自定义Hook的老人都应该能从里面找到一点之前没注意过的东西。1. 先把思路理清楚useHash 到底在解决什么问题1.1 一个让我决定写 useHash 的真实场景之前我维护一个数据报表平台页面里有时间范围、维度、指标、分页、还有几个Tab页签。产品提了个需求用户刷新页面之后之前选好的筛选条件要保持住而且最好能让用户把一个筛选好的页面链接直接发给同事对方打开就是一样的状态。当时我脑子里过了几个方案。塞 localStorage 最简单但分享链接这个需求直接把它否了用 query 参数后端日志会被各种无关参数污染而且有些网关会对 URL 长度做限制改造项目上路由框架又太重了为了几个筛选条件引入一套路由体系没必要。最后我盯上了 URL hash。它刷新不丢失链接天然携带状态不需要额外请求后端浏览器前进后退还能自动支持。一个 useHash 就能把这些需求全包住这就是我写这个 Hook 的起点。1.2 hash 和普通 React state 的本质区别很多人以为 useHash 就是把 useState 的值和 location.hash 同步一下听起来简单但它的底层模型和 useState 完全不同。能力useStateuseHash刷新页面后状态丢失保留通过链接分享状态做不到天然支持浏览器前进/后退不参与自动参与是否触发服务端请求否否同一页面多个组件同步靠共享状态靠统一订阅外部源服务端渲染正常需要特殊处理useState 的状态在内存里和外部世界隔离useHash 的状态绑定在地址栏上读取是同步的、确定的谁打开这个 URL谁就能看到同一份状态。它本质上不是“React 内部状态”而是一个挂在浏览器全局环境里的外部数据源React 组件只是它的一个观察者。1.3 什么场景适合 useHash什么场景建议绕道我的经验是hash 适合承载“低频、可分享、不敏感”的界面状态。低频比如 Tab 切换、抽屉/弹窗显隐、折叠面板。为什么强调低频因为默认情况下每次给 location.hash 赋值都会往历史记录里 push 一条记录用户在几个 Tab 之间疯狂切换浏览器历史会被刷屏后退按钮按十几次才能离开页面体验很差。可分享筛选条件、当前页码、关键词这类用户希望别人打开链接就能看到的。不敏感不要把 token、用户手机号这类信息往 hash 里塞。hash 会出现在浏览器历史、分享链接、部分第三方统计系统里泄露风险比大多数人想象的高。不适合的场景也很明确核心路由不要用它。路径匹配、嵌套路由、懒加载映射、权限控制这些工作路由库已经做了太多你拿 useHash 裸写最后基本都会在某一次需求变更后返工。我见过有人想自己实现一个 hash 路由后来照抄了 react-router 一半的功能既不完整还难维护。2. 先做一个“能用版”然后看看它藏了多少坑2.1 十行代码的朴素实现如果只是想尽快跑通绝大多数人会写一个这样的 Hookfunction useHash() { const [hash, setHash] useState(() window.location.hash); useEffect(() { const onHashChange () setHash(window.location.hash); window.addEventListener(hashchange, onHashChange); return () window.removeEventListener(hashchange, onHashChange); }, []); const updateHash (value: string) { window.location.hash value; }; return [hash, updateHash]; }代码很短思路直白初始化时读一次当前 hash然后监听 hashchange 事件等 hash 变了就 setState。这个版本在简单页面里能用但如果你把它直接搬进正式项目大概率会踩到下面几个问题。2.2 坑一首帧和监听绑定之间存在时间窗useState 的初始值在组件 render 阶段读取而 hashchange 的监听在 useEffect 里才注册。两者之间存在一个时间窗口如果在这个窗口期间hash 被外部改变了组件里存的 hash 就只有初始值事件监听又已经错过了那次变化。这个场景听起来极端但我真的遇到过。项目里有个页面被嵌在 iframe 里父页面通过修改 src 来切换页面并且会在加载完成后立即修改 hash。React 组件渲染速度稍微慢一点useState 拿到的初值就已经过期了而 useEffect 还没来得及监听新值最终状态丢了一半。更常见的场景是用户快速连点浏览器的前进/后退按钮页面还没来得及挂载完hash 已经连续跳了两次朴素实现只收到最后一次中间状态全部丢失。2.3 坑二多个组件同时使用时状态各有各的版本假设页面里有两个组件都调用了这个 useHash。它们各持有一份 useState各注册一个 hashchange 监听。大多数时候能工作但这里有一个隐患hash 作为外部数据源它的“权威值”只有一个而组件里的状态是你手动复制出来的副本。一旦某个组件因为渲染时机问题没有及时 setState页面上就会短暂出现两个组件状态不一致的中间态。这只是一种可能性更根本的问题在于这个 Hook 没有统一的数据源React 的调度机制无法保证多个副本在同一轮渲染里读到一致的值。用 useSyncExternalStore 就是为解决这类问题而生的后面我会展开。2.4 坑三StrictMode 下的重复绑定与清理隐患React 18 之后开发环境默认开启 StrictMode效果是 effect 会执行 mount - unmount - mount。很多人的 useEffect 清理函数写得不严谨或者依赖数组里漏了引用结果就是 window 上绑了多个 hashchange 监听。表现是 hash 一变setState 被连续调用好几次控制台日志刷屏性能也跟着下降。朴素实现如果严格按照上面的代码写StrictMode 下清理函数是正常的问题不大。但当你基于它扩展比如想同时处理 storage 事件、popstate 事件或者在监听回调里访问了一个不稳定的函数引用时很容易在依赖数组上犯错。这类 bug 最恶心的点是开发模式一切正常线上偶尔抽风排查起来非常费劲。3. 生产级 useHash 是怎么一步步打磨出来的3.1 为什么我最终选了 useSyncExternalStoreReact 18 提供了一个专门用于订阅外部数据源的 HookuseSyncExternalStore。它的定位就是解决“外部 store 与 React 渲染状态同步”的问题和 useEffect setState 那套手动同步方案相比有本质区别。const state useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);它接收三个参数subscribe 负责订阅外部源getSnapshot 负责读取当前快照getServerSnapshot 负责在服务端渲染时提供初始值。React 内部会保证所有订阅了同一个外部源的组件在同一轮渲染中读取到完全一致的快照不会出现我前面说的“副本各持己见”的中间态。理解它可以把外部数据源想象成一个广播电台React 组件是收音机。旧的方案里每台收音机自己录一遍再播放时机稍有偏差内容就不同步useSyncExternalStore 是所有收音机共用一个信号塔时刻保持一致。3.2 一个 40 行的基准实现下面这段是我项目里最基础的 useHash 版本TypeScript React 18可以直接复制使用import { useSyncExternalStore, useCallback } from react; function subscribe(callback: () void) { window.addEventListener(hashchange, callback); return () { window.removeEventListener(hashchange, callback); }; } function getHashSnapshot(): string { return window.location.hash; } function getServerSnapshot(): string { return ; } export function useHash(): [string, (nextHash: string) void] { const hash useSyncExternalStore(subscribe, getHashSnapshot, getServerSnapshot); const setHash useCallback((nextHash: string) { const normalized nextHash.startsWith(#) ? nextHash : #${nextHash}; if (window.location.hash normalized) { return; } window.location.hash normalized; }, []); return [hash, setHash]; }这个版本已经解决了多组件同步和首帧时间窗的问题。你可能会问getHashSnapshot 每次返回的都是 window.location.hash为什么不会死循环这里有个关键点如果 hash 没有变化window.location.hash 返回的还是同一个字符串值Object.is 比较结果是相等的React 就认为快照没变不会触发额外渲染。但如果你在 getSnapshot 里做了派生操作比如拼接字符串每次调用都会生成新引用React 会觉得快照一直在变页面直接死循环。这个细节我后面会专门讲。3.3 三个设计取舍返回值形态、自动补号和历史记录策略第一返回值用数组还是对象。基准实现用了数组贴合 useState 的解构习惯。但我后面给正式版加了解析参数、replace 模式等功能之后果断换成了对象返回。原因很简单数组解构要求调用方记住每个位置的语义东西一多就乱了对象可以让方法名自解释。第二setter 要不要自动补#。要补。业务代码里使用者通常只知道状态内容是from2024-01-01to2024-01-31不会关心地址栏格式。你在 setter 里补全#统一处理#前缀可以省掉每个调用点的大量重复判断。反过来读取的时候也要能容忍用户传入带#或不带#的字符串所以 normalize 的逻辑必须稳。第三历史记录默认 push 还是 replace。window.location.hash value默认往 history 里 push 一条新记录用户能通过后退回到上一个状态。这适合“页面流程可回溯”的场景比如步骤条、Tab 跳转。但如果是筛选联动这种高频操作每改一个下拉框就 push 一条记录用户想退出页面要按十几次后退那体验就很差了。所以一个完整的 useHash 应该同时提供 push 和 replace 两种写模式业务自己决定频率高低这就是我代码里同时保留 setHash 和 setHashReplace 的原因。3.4 进阶把 hash 当成一个可解析的状态仓库只拿到原始 hash 字符串对业务来说远远不够。日常最实用的形态是#key1value1key2value2这种键值对。我封装了 parseHash、stringifyHashParams 和 useHashParams 三个配套函数让调用方直接消费对象而不是自己拆字符串。export function parseHashT extends Recordstring, string | undefined(hash: string): T { const rawHash hash.startsWith(#) ? hash.slice(1) : hash; if (!rawHash) { return {} as T; } const params: Recordstring, string {}; for (const segment of rawHash.split()) { if (!segment) { continue; } const equalIndex segment.indexOf(); if (equalIndex -1) { params[safeDecode(segment)] ; } else { const key safeDecode(segment.slice(0, equalIndex)); const value safeDecode(segment.slice(equalIndex 1)); params[key] value; } } return params as T; } export function stringifyHashParams(params: Recordstring, string | undefined): string { const entries Object.entries(params) .filter(([, value]) value ! undefined value ! ) .map(([key, value]) ${encodeURIComponent(key)}${encodeURIComponent(value!)}); return entries.length 0 ? #${entries.join()} : ; } function safeDecode(text: string) { try { return decodeURIComponent(text); } catch { return text; } }使用的时候组件里只需要这样const params useHashParams{ from?: string; to?: string; keyword?: string }();然后把 stringifyHashParams 的结果传给 setHash。这套封装在筛选、搜索、分页场景里非常好用业务代码几乎不感知 hash 的存在只觉得自己在用普通对象状态。这里有一个注意点safeDecode 里的 try/catch 不是多余的。用户可能通过分享链接传入一个非法编码比如#name%E4%B8%AD这种被截断的编码串直接 decodeURIComponent 会抛 URIError导致整个组件崩溃。降级返回原始字符串看起来不优雅但至少不会把页面搞挂。3.5 进阶replaceState 模式与手动事件的坑用 history.replaceState 更新 hash好处是不留历史记录。但有一个必须处理的副作用replaceState 本身不会触发 hashchange 事件你改了地址栏React 却毫不知情。正确的做法是更新完 URL 之后手动派发一个 HashChangeEventconst setHashReplace useCallback((nextHash: string) { const normalized nextHash.startsWith(#) ? nextHash : #${nextHash}; const url ${window.location.pathname}${window.location.search}${normalized}; window.history.replaceState(null, , url); window.dispatchEvent(new HashChangeEvent(hashchange)); }, []);手动 dispatch 事件是为了让 useSyncExternalStore 的 subscribe 机制感知到变化从而触发 React 重新渲染。这个技巧看起来有点 hack但它是在不引入额外状态管理的前提下最干净、最贴近浏览器原生语义的解决方案。4. 常见问题与排查技巧实录4.1 页面死循环先查 getSnapshot 的返回值稳定性这是 useSyncExternalStore 使用者最容易踩的坑也是最难排查的之一。React 内部会用 Object.is 比较 getSnapshot 前后两次的返回值只要你不稳定它就认为外部 store 一直在变然后不停触发渲染最终页面卡死或者疯狂报错。最常见的错误写法是在 getSnapshot 里做字符串拼接或解析function getSnapshot(): string { return #${window.location.hash.replace(#, )}; // 错误示例 }每次调用都产生一个新字符串即使内容相同引用也不同无限循环由此开始。正确的做法是 getSnapshot 只返回最原始的值所有派生逻辑放到 useMemo 或组件内部执行。如果确实需要返回一个对象也要在外面做一层缓存保证引用稳定。4.2 设置相同 hash 后组件不更新正常逻辑里如果 window.location.hash 和当前值相同浏览器不会触发 hashchange这是标准行为。但你可能会遇到产品提需求“用户点击同一个 Tab 也要刷新数据”。这时你不能直接忽略相同值的赋值。解决思路有两个。一个是比较后短路这是基准实现里return的行为适合大多数场景另一个是在 setter 里不比较总是先赋值然后手动 dispatch 一个 hashchange 事件强制通知 React 更新。后者的代价是这次渲染拿到的 hash 和之前没变化你需要结合一个额外的版本号字段来触发副作用。我的建议是普通业务用前者特殊的“强制刷新”需求用后者并且把这个差异在命名上写清楚比如 setHashForce。4.3 中文参数乱码与浏览器差异把中文塞进 hash如果不做任何编码不同浏览器的行为会不一样。有的浏览器会自动把非 ASCII 字符转成百分号编码有的则原样保留导致不同浏览器里同一个链接读出来的 hash 字符串不同。正确做法是统一在写入时用 encodeURIComponent读取时用 decodeURIComponent并且成对出现。千万不要只编码不解码或者在 parseHash 里提前把整个 hash 用 decodeURIComponent 解码一次那样碰到包含%的原始值时会直接抛异常。我上面给的 parseHash 实现里safeDecode 就是为了兜住这类错误。4.4 和 react-router 的 HashRouter 打架了如果项目已经用了 react-router 的 HashRouter那 hash 就是路由的领地你再自己写一套 useHash 去直接操作 location.hash很容易互相覆盖最常见的是 useHash 的写入把路由路径清掉了。我的建议是明确边界在 HashRouter 管理的子树里useHash 只读不写。读 hash 来做一些状态同步没问题写操作一律走路由 API。如果项目里同时存在两种需求更彻底的方案是把 hash 里的路径部分和状态部分用分隔符隔离但这么做维护成本不低我实际做过一次之后就不推荐了升级路由库时解析逻辑会让你崩溃。4.5 跨标签页同步别指望 hashchange 自己通知别人不少同事问过我浏览器两个标签页都开着同一个页面A 标签页改 hash 后 B 标签页能不能收到通知答案是不能。hashchange 事件只作用于当前文档每个标签页的 location 对象是独立的A 标签页修改 URL 不会改变 B 标签页的地址。如果产品确实需要多标签同步筛选器状态正确做法是把状态同时写入 localStorage通过 storage 事件或 BroadcastChannel 通知其他标签页由对方自己调用 setHash 来更新地址栏。跨标签页同步本身是个不小的课题别指望一个 useHash 全搞定。现象根因对策页面死循环渲染getSnapshot 返回不稳定快照只返回原始值不做任何加工相同 hash 赋值但不刷新浏览器不触发 hashchange比较后短路或手动 dispatch 事件中文参数乱码各浏览器编码行为不一致encode/decodeURIComponent 成对使用与路由库互相覆盖同一 hash 被两套逻辑写入明确读写边界useHash 只读多标签页状态不同步hashchange 只在当前文档生效用 storage 事件或 BroadcastChannel 通知5. 我在项目里的最终取舍与参考实现5.1 什么时候我仍然选择 useHash 而不是上路由经历了这些坑之后我对 useHash 的使用边界反而更清楚了。像是报表页的筛选面板、设置页的 Tab、编辑器里的视图模式切换这些场景我基本都会直接上 useHash。它们有几个共同点状态少、不需要嵌套、不需要权限控制、用户有分享诉求。反过来如果页面已经存在认证、路由守卫、嵌套布局我不会为了省事绕过路由库去操作 hash那只会给未来的自己埋雷。一句话总结useHash 定位是“地址栏状态同步器”不是“简易路由”。5.2 我压箱底的最终版 useHash把前面所有设计合到一起这是我目前项目里维护的版本import { useCallback, useMemo, useSyncExternalStore } from react; function subscribe(callback: () void) { window.addEventListener(hashchange, callback); return () window.removeEventListener(hashchange, callback); } function getHashSnapshot() { return window.location.hash; } function getServerSnapshot() { return ; } export function useHash() { const hash useSyncExternalStore(subscribe, getHashSnapshot, getServerSnapshot); const setHash useCallback((nextHash: string) { const normalized nextHash.startsWith(#) ? nextHash : #${nextHash}; if (window.location.hash normalized) return; window.location.hash normalized; }, []); const setHashReplace useCallback((nextHash: string) { const normalized nextHash.startsWith(#) ? nextHash : #${nextHash}; const url ${window.location.pathname}${window.location.search}${normalized}; window.history.replaceState(null, , url); window.dispatchEvent(new HashChangeEvent(hashchange)); }, []); return { hash, setHash, setHashReplace, params: useHashParamsInternal(hash) }; } function useHashParamsInternal(hash: string) { return useMemo(() parseHashRecordstring, string | undefined(hash), [hash]); }实际使用时我很少直接消费原始 hash 字符串基本都是通过 params 对象来读写。筛选组件里的代码大概是这样的形态const { params, setHashReplace } useHash(); const updateKeyword (keyword: string) { setHashReplace(stringifyHashParams({ ...params, keyword })); };这样每次筛选条件变化都只替换当前历史记录用户后退时不会陷进筛选历史的汪洋大海里。5.3 一个让 useHash 更好用的延伸技巧最后分享一个我常用的小技巧hash 变化后自动恢复页面内滚动位置。很多详情页或列表页在改变筛选条件后需要滚动到顶部而用户点击浏览器的后退按钮时又希望回到之前浏览的位置。你可以监听 hash 变化在更新前记录当前滚动位置更新后根据 hash 值恢复。具体实现不复杂在订阅回调里读取 document.scrollingElement.scrollTop把值和 hash 组合成一个缓存对象等组件根据 hash 重新渲染后再从缓存里恢复。这个能力如果直接写进 useHash 里会显得耦合过高我通常会在业务组件里配合 useEffect 实现。地址栏本来的锚点定位功能是浏览器内置的带#content的链接会自动跳到 id 为 content 的元素但当你把 hash 用于状态管理时这个默认行为反而会成为干扰记得在关键页面把它屏蔽掉。hash 这个东西功能简单却总在意想不到的地方给你上课。它既不是银弹也不是上古遗留物把它放在正确的位置它就能让页面状态变得可回溯、可分享、可恢复这也是我折腾 useHash 这么久最大的心得。