企业官网建设流程全解析

做前端这么多年，我一直觉得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 完全不同。

useState 的状态在内存里，和外部世界隔离；useHash 的状态绑定在地址栏上，读取是同步的、确定的，谁打开这个 URL，谁就能看到同一份状态。它本质上不是“React 内部状态”，而是一个挂在浏览器全局环境里的外部数据源，React 组件只是它的一个观察者。

1.3 什么场景适合 useHash，什么场景建议绕道

我的经验是，hash 适合承载“低频、可分享、不敏感”的界面状态。

• 低频：比如 Tab 切换、抽屉/弹窗显隐、折叠面板。为什么强调低频？因为默认情况下每次给 location.hash 赋值都会往历史记录里 push 一条记录，用户在几个 Tab 之间疯狂切换，浏览器历史会被刷屏，后退按钮按十几次才能离开页面，体验很差。
• 可分享：筛选条件、当前页码、关键词这类用户希望别人打开链接就能看到的。
• 不敏感：不要把 token、用户手机号这类信息往 hash 里塞。hash 会出现在浏览器历史、分享链接、部分第三方统计系统里，泄露风险比大多数人想象的高。

不适合的场景也很明确：核心路由不要用它。路径匹配、嵌套路由、懒加载映射、权限控制这些工作路由库已经做了太多，你拿 useHash 裸写，最后基本都会在某一次需求变更后返工。我见过有人想自己实现一个 hash 路由，后来照抄了 react-router 一半的功能，既不完整还难维护。

2. 先做一个“能用版”，然后看看它藏了多少坑

2.1 十行代码的朴素实现

如果只是想尽快跑通，绝大多数人会写一个这样的 Hook：

function 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 为什么我最终选了 useSyncExternalStore

React 18 提供了一个专门用于订阅外部数据源的 Hook：useSyncExternalStore。它的定位就是解决“外部 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 要不要自动补#。要补。业务代码里使用者通常只知道状态内容是from=2024-01-01&to=2024-01-31，不会关心地址栏格式。你在 setter 里补全#，统一处理#前缀，可以省掉每个调用点的大量重复判断。反过来，读取的时候也要能容忍用户传入带#或不带#的字符串，所以 normalize 的逻辑必须稳。

第三，历史记录默认 push 还是 replace。window.location.hash = value默认往 history 里 push 一条新记录，用户能通过后退回到上一个状态。这适合“页面流程可回溯”的场景，比如步骤条、Tab 跳转。

但如果是筛选联动这种高频操作，每改一个下拉框就 push 一条记录，用户想退出页面要按十几次后退，那体验就很差了。所以一个完整的 useHash 应该同时提供 push 和 replace 两种写模式，业务自己决定频率高低，这就是我代码里同时保留 setHash 和 setHashReplace 的原因。

3.4 进阶：把 hash 当成一个可解析的状态仓库

只拿到原始 hash 字符串，对业务来说远远不够。日常最实用的形态是#key1=value1&key2=value2这种键值对。我封装了 parseHash、stringifyHashParams 和 useHashParams 三个配套函数，让调用方直接消费对象，而不是自己拆字符串。

export function parseHash<T extends Record<string, string | undefined>>(hash: string): T { const rawHash = hash.startsWith('#') ? hash.slice(1) : hash; if (!rawHash) { return {} as T; } const params: Record<string, 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: Record<string, 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 之后，手动派发一个 HashChangeEvent：

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')); }, []);

手动 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 全搞定。

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(() => parseHash<Record<string, 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 这么久最大的心得。