企业官网建设流程全解析

ZCode 的前端构建于 React 之上，其渲染层包含大量useEffect副作用调用，Effect 依赖的宽窄直接影响渲染性能。本文是 ZCode 内置的 React/Next.js 性能优化技能包（.agents/skills/react-best-practices/）中rerender-dependencies规则的深度解读，从依赖收窄的原理、正确写法到派生状态处理，完整覆盖该规则并辅以仓库源码佐证，读完即可在真实组件中落地"最小化 Effect 重跑"的优化手法。

规则速览：一条规则、两个关键点

规则文件.agents/skills/react-best-practices/rules/rerender-dependencies.md以 YAML front-matter 定义了这条规则的元信息：

在技能包的分类体系中，该规则隶属于Re-render Optimization（重渲染优化）类别，前缀为rerender-。根据.agents/skills/react-best-practices/rules/_sections.md中的定义，该类别的影响等级为MEDIUM（中），其宗旨是"减少不必要的重渲染，从而最小化浪费的计算并提升 UI 响应性"。

规则本身只有两条核心要求：

1. 优先使用原始类型（primitive）依赖，而非对象依赖，以减少 Effect 的重复执行；
2. 对于派生状态（derived state），应在渲染期间计算，而不是在 Effect 内部计算。

为什么对象依赖会"过度触发"？

React 的useEffect依赖数组采用引用比较（Object.is）判定依赖是否变化。这意味着：

• 对于number、string、boolean等原始类型，比较的是值；
• 对于对象、数组、函数等引用类型，比较的是引用地址。

因此，当 Effect 依赖一个对象（如user）时，只要该对象的引用发生变化——哪怕只是其中某个字段被更新——React 就会判定依赖"已变化"，从而重新执行 Effect。

这一点在本仓库中可以直接得到印证。在 GitPane.tsx 中有如下代码：

useEffect(() => { onFileChangeFindMatchCountChange(fileChangeFindState.total); }, [fileChangeFindState.total, onFileChangeFindMatchCountChange]);

这里依赖的是fileChangeFindState.total（一个原始数值字段）而非整个fileChangeFindState对象，正是"收窄依赖"的典型应用——只有当查找匹配总数真正变化时才通知外部。

反例与正例：从[user]到[user.id]

规则文件给出了最经典的对比：

// Incorrect（反例）：用户任意字段变化都会触发重跑 useEffect(() => { console.log(user.id); }, [user]); // Correct（正例）：仅当 id 变化时才触发重跑 useEffect(() => { console.log(user.id); }, [user.id]);

反例的问题：user是对象，只要user.name、user.email、user.avatar等任一字段被更新，即使user.id完全没有变，Effect 也会重新执行。对于日志、埋点、网络请求等副作用而言，这是纯粹的浪费。

正例的收益：只依赖user.id这个原始类型字段，Effect 的执行频率被严格限制在"id 真正变化"这一事件上，副作用次数与业务语义精确对齐。

规则文件中的原话是："Specify primitive dependencies instead of objects to minimize effect re-runs"（使用原始类型依赖替代对象依赖以最小化 Effect 重跑）。

派生状态：把计算移出 Effect

规则文件的第二个要点针对"在 Effect 内部做条件判断"的写法，其本质是依赖粒度与数据粒度不匹配的问题：

// Incorrect（反例）：width 从 767、766、765... 一路变化时 Effect 会一路重跑 useEffect(() => { if (width < 768) { enableMobileMode(); } }, [width]); // Correct（正例）：仅在布尔值翻转时才触发 const isMobile = width < 768; useEffect(() => { if (isMobile) { enableMobileMode(); } }, [isMobile]);

反例的问题：width是一个连续变化的值（例如窗口拖拽时可能经历 767、766、765…），依赖[width]意味着 Effect 每次宽度变化都会执行，虽然内部有width < 768判断，但判断在 Effect 内部进行，无法阻止 Effect 本身被反复调用。

正例的思路：将width < 768提升为渲染期计算出的派生布尔值isMobile。布尔值只有true/false两种取值，Effect 只会在布尔值翻转时执行一次，把"多次无关执行"压缩为"一次有效执行"。

本仓库中的 ChatMediaAttachmentPreviewDialog.tsx 也体现了类似的"先派生、再订阅"思路：

const isVideo = attachment?.mediaType.startsWith("video/") === true; const isPdf = attachment?.mediaType.split(";", 1)[0]?.trim().toLowerCase() === "application/pdf"; const [videoState, setVideoState] = useState<"loading" | "ready" | "unsupported">("loading"); useEffect(() => { setVideoState("loading"); }, [attachment?.mediaType, attachment?.url, open]);

isVideo、isPdf这两个派生布尔值在渲染期直接算出，供 JSX 与后续逻辑复用；Effect 则依赖attachment?.mediaType、attachment?.url与open这三个字段级的值，而不是整个attachment对象。

两个常见误区

误区一：空依赖数组 + 内部条件判断

// 看似"只在挂载时执行"，实则是把"每次重渲染都执行"藏进了依赖数组 useEffect(() => { if (width < 768) { enableMobileMode(); } }, []);

[]意味着 Effect 只在挂载时执行一次，内部读取的width永远是最初的值，之后窗口变化时逻辑永远不会再触发。这既是 bug，也违背了规则。

误区二：依赖了对象却又不用它的字段

useEffect(() => { analytics.track(pageViewId); }, [analytics]); // analytics 是对象，任何引用变化都会重跑

效果与[user]完全一致：只要analytics引用变化就重跑。正确写法是只依赖真正用到的原始字段。

进阶补充：与相邻规则的配合

在技能包中，rerender-dependencies并非孤立存在，它与同类的几条规则共同构成完整的重渲染优化体系（参见 SKILL.md 中的规则索引）：

拆分独立副作用：当一个 Effect 内包含多个不相关的副作用时，即使各自依赖都收窄了，任一依赖变化仍会触发整个 Effect。此时应参考rerender-split-combined-hooks（.agents/skills/react-best-practices/rules/rerender-split-combined-hooks.md）将其拆成多个 Effect：

// 反例：pathname 或 pageTitle 任一变化，两个副作用都执行 useEffect(() => { analytics.trackPageView(pathname); document.title = `${pageTitle} | My App`; }, [pathname, pageTitle]); // 正例：两个副作用各自收窄依赖、独立触发 useEffect(() => { analytics.trackPageView(pathname); }, [pathname]); useEffect(() => { document.title = `${pageTitle} | My App`; }, [pageTitle]);

关于 React Compiler：如果项目启用了 React Compiler（自动记忆化编译器），它会自动优化依赖跟踪，部分场景下可代为处理上述问题——但即便如此，理解并主动写出"窄依赖"仍是基本功。

实践检查清单

在 ZCode 及任何 React 项目中审查或编写useEffect时，可对照以下清单：

• 依赖数组是否只包含 Effect 内实际读取的值？
• 依赖的是对象，还是对象中真正需要的原始字段（如user.id而非user）？
• Effect 内部的条件判断（如width < 768）是否已提前为派生布尔值，并依赖该布尔值而非连续值？
• 多个相互独立的副作用是否已拆分为独立 Effect？
• 是否存在"空依赖数组 + 内部读取外部值"的隐性 bug？
• 若项目启用了 React Compiler，是否已确认其自动优化生效、无需手动干预？

更多阅读

• 本规则完整源码：.agents/skills/react-best-practices/rules/rerender-dependencies.md
• 技能包总览与规则索引：.agents/skills/react-best-practices/SKILL.md
• 全部规则合并版：.agents/skills/react-best-practices/AGENTS.md（其中### 5.7 Narrow Effect Dependencies一节为本文规则的合并形态）
• 类别划分与优先级定义：.agents/skills/react-best-practices/rules/_sections.md
• 规则编写模板：.agents/skills/react-best-practices/rules/_template.md
• 仓库中的真实应用示例：GitPane.tsx、ChatMediaAttachmentPreviewDialog.tsx