企业官网建设流程全解析

Sanity 仓库中的 React 性能规则解读：将状态读取延迟到实际使用点（rerender-defer-reads）

【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity

本文基于 Sanity 仓库内置的 Agent 技能文档 rerender-defer-reads.md，详解 Vercel React 最佳实践中的一条中优先级重渲染优化规则：当searchParams、localStorage等动态状态只在回调中被使用时，不要通过 Hook 订阅它们，而应在事件触发的那一刻按需读取。读完本文，你将理解订阅式读取与按需读取的本质区别、该规则在 Sanity 仓库技能体系中的定位，以及它如何与js-cache-storage等配套规则组合，减少 React 组件的无效重渲染。

规则定位：Sanity 仓库内的技能体系与元数据

该文档是 Sanity 仓库中vercel-react-best-practices技能的一部分。技能入口 SKILL.md（版本 1.0.0，MIT 许可）声明这是一份面向 React 与 Next.js 的 57 条性能优化规则集，"should be used when writing, reviewing, or refactoring React/Next.js code"，并按影响程度分为 8 个优先级类别。rerender-defer-reads属于其中第 5 类：

在 SKILL.md 的 Quick Reference 中，该规则的一行描述是："Don't subscribe to state only used in callbacks"（不要订阅只在回调中使用的状态）。

规则文件本身通过 YAML frontmatter 携带机器可读的元数据，这也是整个技能体系可被 Agent/LLM 自动检索与引用的关键设计：

--- title: Defer State Reads to Usage Point impact: MEDIUM impactDescription: avoids unnecessary subscriptions tags: rerender, searchParams, localStorage, optimization ---

• impact: MEDIUM表示这是一条中等收益的优化：单独看不会显著改变首屏性能，但在大型应用中累积的无效订阅会放大重渲染范围；
• tags中同时出现searchParams和localStorage，说明该规则覆盖两类动态状态源，而不局限于 URL 参数。

同一条规则的完整展开版位于技能汇总文档 AGENTS.md 的第 5 章 "Re-render Optimization" 的5.2 节（标注为Impact: MEDIUM (avoids unnecessary subscriptions)），内容与规则文件一致，可交叉验证。仓库中skills/与.agents/skills/两个目录存放了同一套规则，前者供人类阅读、后者供 Agent 消费。

核心原则：回调专用状态不应建立订阅

规则原文只有一句话，但信息密度很高：

Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.如果你只在回调中读取某个动态状态（searchParams、localStorage），就不要为它建立订阅。

关键区分在于"读取发生的位置"：

• 渲染期间读取（render-time read）：状态值参与 JSX 输出或派生 props。此时订阅是必要的，因为 UI 必须随状态变化而更新；
• 回调中读取（callback-time read）：状态值只在onClick、onSubmit等事件处理函数里被消费。此时 UI 并不依赖它的当前值，组件完全没有理由因为它的变化而重渲染——却常常因为"顺手"调用了useSearchParams()之类的 Hook 而建立了一条全量订阅。

错误示例：为回调专用的参数建立了全量订阅

以下是规则文档给出的 Incorrect 版本，完整保留：

function ShareButton({chatId}: {chatId: string}) { const searchParams = useSearchParams() const handleShare = () => { const ref = searchParams.get('ref') shareChat(chatId, {ref}) } return <button onClick={handleShare}>Share</button> }

问题所在：useSearchParams()返回的对象绑定在当前 URL 的 query 上，任何参数变更（用户添加?utm_source=x、路由内navigate携带新 query 等）都会让searchParams引用变化，从而触发ShareButton整体重渲染——哪怕这个按钮的渲染输出Share一个字都没变。按钮每多订阅一个 query 参数，就为全局 URL 变化多付一次渲染成本。

正确示例：把读取推迟到事件发生的那一刻

规则文档给出的 Correct 版本：

function ShareButton({chatId}: {chatId: string}) { const handleShare = () => { const params = new URLSearchParams(window.location.search) const ref = params.get('ref') shareChat(chatId, {ref}) } return <button onClick={handleShare}>Share</button> }

改动只有两处，语义完全不同：

1. 删除渲染期的 Hook 调用——组件不再订阅searchParams，URL 变化不再引发它重渲染；
2. 在回调内部构造URLSearchParams——window.location.search在事件被处理的那一刻返回的是当时的 URL 字符串（location.search是活属性，history.pushState/replaceState导航后它始终反映最新地址），因此按需构造出来的params与订阅版本在"点击瞬间"读取到的值完全一致，但代价为零：没有订阅、没有重渲染、只在真正需要值时才做一次解析。

可以概括为一条判定式：状态是否进入组件的输出？是 → 订阅；否（仅回调消费）→ 延迟读取。

原理解析：为什么"订阅"比"读取"昂贵

从 React 数据流的角度看，这类 Hook（以 React Router 的useSearchParams为代表）的返回对象依赖底层 location 状态；每当 query 变化，订阅它的组件进入重渲染队列。而ShareButton的渲染产物是纯静态 JSX，重渲染是纯粹的浪费——V8 层面要重新执行函数体、React 层面要做 diff、还要检查子树是否有 memo 中断。

反过来，window.location.search的读取是一次字符串访问，new URLSearchParams(...)是一次 O(query 长度) 的解析，都发生在用户显式触发的时刻。这类"惰性读取"（deferred read）的隐含前提是：

• 值在事件发生时才需要：分享链接的ref参数只需在点击"Share"那一刻是准确的即可，页面生命周期内它中途变化了也不影响任何已渲染的 UI；
• 读取点是浏览器环境：window.location只在客户端可用。本规则的正确示例恰好把读取放在onClick回调里——浏览器事件回调天然只会在 hydration 之后运行，因此不需要额外的typeof window守卫；但如果把window.location.search提到模块顶层或useEffect之外的渲染逻辑中，就要重新评估 SSR 场景。

同一规则对 localStorage 的适用方式

frontmatter 的 tags 中并列了searchParams与localStorage，因为两者的"订阅陷阱"同构：

• 反模式：在渲染期间直接localStorage.getItem(key)并把结果用于 props/条件分支（若配合了useEffect+setState来"监听"变化，更是每次 storage 变更都引发一轮渲染），而该值实际只在某个提交回调里被读取；
• 修正：把localStorage.getItem(key)移进事件处理函数内部，在事件触发时同步读取即可，storage 的读取是同步的、立即可用的，不存在"错过变化"的问题。

配套规则：按需读取 + 结果缓存的组合拳

该规则在技能体系中并不是孤立的。同属 JavaScript Performance 类的 js-cache-storage.md 指出localStorage、sessionStorage、document.cookie是同步且昂贵的 I/O，建议用内存 Map 缓存读取结果：

const storageCache = new Map<string, string | null>() function getLocalStorage(key: string) { if (!storageCache.has(key)) { storageCache.set(key, localStorage.getItem(key)) } return storageCache.get(key) } function setLocalStorage(key: string, value: string) { localStorage.setItem(key, value) storageCache.set(key, value) // keep cache in sync }

两条规则合起来构成一个完整的处理链路：先判断"是否真的需要在渲染期感知该状态"（rerender-defer-reads，能不订阅就不订阅），再对确实要反复读取的 storage 访问做 Map 级缓存（js-cache-storage）。js-cache-storage 还特别提示了缓存失效策略：当 storage 可能被外部变更（其他标签页写入、服务端设置的 cookie）时，监听storage事件按 key 失效、在visibilitychange回到可见态时清空缓存：

window.addEventListener('storage', (e) => { if (e.key) storageCache.delete(e.key) }) document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'visible') { storageCache.clear() } })

此外，Re-render Optimization 类中与本规则思路相邻的还有 rerender-derived-state.md（订阅派生布尔值而非原始值）与 rerender-use-ref-transient-values.md（高频瞬态值用 ref 承载），它们共同回答同一个问题：哪些"读"必须参与 React 的响应式依赖图，哪些可以留在依赖图之外。

适用边界与注意事项

规则给出的收益是 MEDIUM，落地时仍需注意以下边界：

1. 值参与了渲染就必须保留订阅。如果ref参数要显示在按钮文案上（如"Shared via {ref}"），那它就是渲染依赖，必须继续用useSearchParams()，按需读取反而会丢失响应性；
2. 效果（effect）中消费的参数同理。若某个useEffect需要"query 一变就执行逻辑"，订阅是 effect 依赖的必然要求，不属于本规则针对的"仅回调使用"场景；
3. 服务端渲染环境。window.location只在浏览器存在，按需读取应始终保留在浏览器回调（事件处理、useEffect 之后）内执行；
4. 多标签页场景。window.location.search只反映当前标签页的 URL，这与useSearchParams()的行为一致（它们都绑定当前文档），按需读取不会引入新的可见性差异；真正需要跨标签页同步的是 storage 类状态，应交给 js-cache-storage 的失效机制处理。

小结

• rerender-defer-reads.md 的核心主张：searchParams、localStorage等动态状态只在回调中使用时，放弃 Hook 订阅，改为在事件触发瞬间读取（new URLSearchParams(window.location.search)/localStorage.getItem(...)），从而消除订阅带来的无效重渲染；
• 该规则在 SKILL.md 中归类为 Re-render Optimization（MEDIUM 优先级、rerender-前缀），完整版见 AGENTS.md 第 5.2 节；
• 落地判据只有一条：状态是否进入组件输出。是 → 订阅；否 → 延迟读取，并可与 js-cache-storage.md 的 Map 缓存策略组合，进一步降低同步 I/O 成本。

【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity