ZCode 前端重渲染优化：把 memo 组件的非原始类型默认参数提升为常量，修复 React memo 失效

• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI

ZCode（智谱 AI 编程工作台）的桌面端与 Web 端 UI 大量使用memo()包裹组件以拦截无关父组件重渲染，但一个常见的隐蔽反模式——在 memo 组件的解构参数里直接写= () => {}、= []、= {}这类默认值——会在每次渲染时新建引用，让memo()的严格相等比较（Object.is）永远不通过，导致组件缓存形同虚设。本指南以 ZCode 仓库内 vendored 的 Vercel React Best Practices 规则集（.agents/skills/react-best-practices/）中的rerender-memo-with-default-value规则为主体，结合packages/ui的真实源码实践，讲解问题的成因、标准修复手法，以及数组/对象/函数三类默认值的一揽子落地方案。读完你将掌握：一眼识别会击穿 memo 的默认参数写法，用模块级常量恢复组件缓存命中，并在团队代码评审中建立可执行的排查清单。

规则出处：Re-render Optimization 分类下的 MEDIUM 影响级规则

该规则完整定义于 rules/rerender-memo-with-default-value.md，同时在聚合文档 .agents/skills/react-best-practices/AGENTS.md 的5.5 节中收录。整份规则集由 Vercel Engineering 维护（skill 元数据见 metadata.json），共 70 条规则、8 大分类，按影响程度排序：

本规则属于第 5 类Re-render Optimization。规则 front-matter 中标注的 impact 为MEDIUM，impactDescription 为"restores memoization by using a constant for default value"，tags 为rerender, memo, optimization——即它的核心价值正是"恢复被无意击穿的 memo 缓存"。同类规则还有 rerender-memo.md（将昂贵计算抽入 memo 组件）等，共同服务于"减少不必要重渲染"这一目标。

问题根源：memo 的浅比较 vs 每次渲染新建的默认值

memo()组件的工作方式是：父组件重渲染时，React 用Object.is（严格相等）逐一比较新旧 props；只有某个 prop 引用变了，才会触发子组件重渲染。非原始类型（函数、数组、对象）的相等性取决于引用而非内容——每次执行解构默认值都会在内存中新建一个实例。

把默认值直接写在解构参数里，相当于"每个 prop 都是新的"：

// 错误写法：onClick 每次渲染都是新函数 const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) { // ... }) // 不传 onClick 时，memo 比较仍以“新值 vs 新值”进行，永远不相等 <UserAvatar />

从源码结构看，这种写法对 memo 的破坏是双向的：组件内部拿到的默认函数每次都是新引用，若它被放进useEffect/useMemo的依赖数组，会连带触发 effect 重跑、缓存重建；组件外部则直接导致 memo 的命中率归零——onClick这一项就足以让浅比较失败，其他 props 哪怕全部相等也会被一并拖着重渲染。

标准修复：把默认值提升为模块级常量

规则给出的修复方式是提取常量，让默认值在模块加载时只创建一次、生命周期内引用恒定：

// 正确写法：NOOP 在模块作用域只创建一次，引用稳定 const NOOP = () => {}; const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) { // ... }) // 不传 onClick 时，新旧两次渲染拿到的是同一个 NOOP，memo 浅比较通过 <UserAvatar />

要点在于"提升"的位置是模块级（组件定义文件顶层），而不是组件内部——组件函数体内的const noop = () => {}同样每次渲染新建，只是把问题换了个位置。只有模块顶层声明才具备跨渲染稳定的引用身份。

ZCode 源码里的真实落法：函数、数组、对象三类默认值

规则文档聚焦函数默认值，但同一原理覆盖数组与对象。ZCode 的packages/ui中已有符合该规则的生产代码，可逐一对照：

1. 函数默认值：NOOP常量（ConversationShareConfirmationDock）

packages/ui/src/v4/ConversationShareConfirmationDock.tsx 在模块顶层声明const NOOP = () => {};，并同时用于多个可选回调的默认值：

const NOOP = () => {}; function ConversationShareConfirmationDockImpl({ ... onTitleChange = NOOP, onAccessModeChange = NOOP, disclosureAccepted = false, onDisclosureAcceptedChange = NOOP, ... }: ConversationShareConfirmationDockProps) {

这类"分享确认面板"需要频繁跟随对话状态变化而更新，回调类 prop 若用内联默认值，任何一次父组件重渲染都会让整棵子树失效。共享同一个NOOP既保证引用稳定，也让多个"无操作"默认值在内存中只占一份。

2. 数组默认值：EMPTY_PINNED_TASKS常量（TaskList）

packages/ui/src/TaskList.tsx 是规则文档场景的完整演绎——memo 组件 + 可选数组参数：

const EMPTY_PINNED_TASKS: ZCodeTaskMeta[] = []; // 父级 App/Shell 可能因 stream 状态更新重渲，但列表 props 本身未变。 // TaskList 先整体 memo，避免无关父 render 重新遍历任务并触发 MemoTaskItem props 计算。 export const TaskList = memo(function TaskList({ ... pinnedTasks = EMPTY_PINNED_TASKS, ...

源码注释直接点明了这层意图：父级可能因流式状态更新而重渲染，TaskList 用 memo 拦截后，只有当 props 真正变化时才重新遍历任务列表。若这里写成pinnedTasks = []，每次渲染新建的空数组就会让 memo 拦截失效，整个任务列表的遍历与MemoTaskItem的 props 计算全部白跑。

3. 对象默认值：EMPTY常量与"引用不变即跳过渲染"（use-timeline-viewport）

packages/ui/src/components/workflow-timeline/use-timeline-viewport.ts 更进一步，把同一思想用于对象值的稳定性保证：

const SCROLLING_MS = 800; const EMPTY: TimelineViewport = { clientWidth: 0, scrollLeft: 0, scrollWidth: 0, scrolling: false };

注释说明：测量到的数值没变就返回上一份对象，ResizeObserver与滚动回调每次造新对象曾让时间线白渲染一轮。代码中merge()函数对三个数值逐一比较，全部相同则返回previous引用——这正是"用恒定引用换取 React 跳过渲染"的通用策略，与规则中"提取常量恢复 memo"的本质一致。

如何在现有代码里排查同类问题

结合本规则与仓库实践，可以沉淀出如下可执行的排查路径（适合 Agent 代码审查与人工评审复用）：

1. 搜 memo 组件定义：查找memo(function/memo(包裹的组件（ZCode 中如TaskList、WorkspaceSidebar、WorkspaceSidebarItem、DesktopWindowFrame、ToolLayout等均为 memo 组件），逐个检查其解构参数中的默认值。
2. 按类型分类默认值：
   • 默认值是() => {}这类箭头函数 → 需提升为NOOP常量；
   • 默认值是[]空数组 → 需提升为EMPTY_X常量；
   • 默认值是{}空对象 → 需提升为EMPTY_X常量。
3. 默认值是否为原始类型可豁免：布尔、数字、字符串等原始类型（如isDesktop = false、taskListHasUnread = false、isDragging = false，见 WorkspaceSidebarItem.tsx）按值比较，不存在引用问题，无需处理。
4. 确认默认常量声明在模块顶层：必须位于组件函数体外，才能保证跨渲染稳定；组件体内的声明无效。

与其他重渲染规则的协同

本规则属于 Re-render Optimization 家族，实践中通常与以下规则组合使用（全部位于 rules/ 目录）：

• rerender-memo：先把昂贵计算抽进 memo 组件（如把头像计算抽成UserAvatar），再用本规则保证该 memo 组件的默认 props 引用稳定，两者是一前一后的配套动作；
• rerender-no-inline-components：不要在组件内部定义组件（每次渲染新建组件类型，memo 完全失效），与本规则同属"引用稳定性"防线；
• rerender-dependencies：effect 依赖用原始值，避免因对象引用不稳定导致 effect 反复触发——本规则修复的默认函数若被放入依赖数组，同样会受益；
• rerender-use-ref-transient-values：高频临时值用 ref 承载，与"常量承载稳定默认值"互补。

另外需要留意适用前提：如果项目启用了 React Compiler，编译器会自动完成这类重渲染优化，手动memo()的必要性会降低（rerender-memo.md 中明确指出了这一边界）。在当前仓库未启用编译器自动优化的场景下，手动遵守本规则仍是低成本、高确定性的手段。

结论与检查清单

rerender-memo-with-default-value这条 MEDIUM 影响级规则解决的是一个极常见但隐蔽的性能陷阱：非原始类型默认值的引用身份不稳定，会让 memo 浅比较永久失败。修复本身只有一行提取动作，收益却是整棵 memo 子树的重渲染拦截恢复生效。

落地时对照以下清单自查：

• memo 组件解构参数中是否有= () => {}/= []/= {}的默认值？
• 是否已将默认值提取为模块顶层常量（如NOOP、EMPTY_PINNED_TASKS、EMPTY）？
• 常量声明位置是否在组件函数体外（模块作用域）？
• 原始类型默认值（false、0、""）是否误改？——无需处理；
• 是否存在组件体内定义的组件/常量，导致引用稳定性问题换汤不换药？

在 ZCode 中，TaskList.tsx、ConversationShareConfirmationDock.tsx、use-timeline-viewport.ts 三处源码可作为团队内部的规范样例，直接作为代码评审时的参照实现。

• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI