ZCode React 性能优化：杜绝在组件内定义组件，修复"每次渲染整树重挂载"陷阱

本文是 ZCode 仓库内置 React 最佳实践技能（.agents/skills/react-best-practices）中 rerender-no-inline-components 规则的深度实战解读。它面向在 ZCode 前端（packages/ui 下的 React/TSX 组件）中编写、评审或重构组件的开发者，帮助你彻底理解"组件内定义组件"为何会导致输入框失焦、动画重置、effect 反复执行等典型性能问题，并掌握以 props 传递数据的正确重构方法，从源码层面杜绝无意义的重挂载。

规则速览：为什么这条规则优先级为 HIGH

该规则在 ZCode 仓库的 React 最佳实践规则库中定义于 rules/rerender-no-inline-components.md，其 frontmatter 明确标注：

• 标题：Don't Define Components Inside Components（不要在组件内定义组件）
• Impact：HIGH——影响等级为"高"
• ImpactDescription：prevents remount on every render（防止每次渲染都发生重挂载）
• 标签：rerender、components、remount、performance

在整套规则库的优先级体系中（见 SKILL.md），rerender- 前缀属于第 5 优先级类别"Re-render Optimization"（重渲染优化）。虽然单个重渲染问题的直接影响通常被归类为 MEDIUM，但"组件内定义组件"这一条被单独标记为 HIGH，原因在于它不是一次多渲染几次的问题，而是每次父组件渲染都会触发子组件整棵子树的卸载与重挂载——这在列表渲染、表单输入、动画场景中会放大为明显的卡顿与交互异常。

问题本质：每次渲染都在创建"全新类型的组件"

React 的调和（reconciliation）机制以元素类型（type）为身份锚点：当两次渲染在相同位置出现的元素 type 相同，React 会复用已有的组件实例（保留 state、DOM 与 effect）；一旦 type 不同，React 会卸载旧实例并全新挂载一个新实例。

在组件内部定义组件时，情况恰好命中后一种分支：

function UserProfile({ user, theme }) {
  const Avatar = () => ( /* ... */ );
  const Stats = () => ( /* ... */ );
  return (
    <div>
      <Avatar />
      <Stats />
    </div>
  );
}

Avatar 和 Stats 是定义在 UserProfile 函数体内的局部箭头函数。函数体每次执行都会重新声明这些函数，得到的是一个个全新的函数对象。对 React 而言，<Avatar /> 的 type 每次渲染都是不同的引用，于是：

1. 旧实例被卸载（unmount）；
2. 新实例被挂载（mount）；
3. 组件内部 state 全部清零；
4. useEffect 的清理函数与 setup 全部重新执行；
5. 底层 DOM 节点被销毁并重建。

这就是 frontmatter 中 "prevents remount on every render" 的含义——修复这条规则的价值，正是阻止每次渲染都发生一次完整的重挂载。

错误写法剖析：为了"省 props"付出的代价

原文档给出的典型反面示例是开发者为了直接访问父组件的变量（theme、user），把子组件写进父组件内部，从而绕过 props 传递：

function UserProfile({ user, theme }) {
  // 定义在内部以访问 `theme` —— 错误
  const Avatar = () => (
    <img
      src={user.avatarUrl}
      className={theme === "dark" ? "avatar-dark" : "avatar-light"}
    />
  );

  // 定义在内部以访问 `user` —— 错误
  const Stats = () => (
    <div>
      <span>{user.followers} followers</span>
      <span>{user.posts} posts</span>
    </div>
  );

  return (
    <div>
      <Avatar />
      <Stats />
    </div>
  );
}

这段代码有两个叠加的问题：

• 身份不稳定：如上一节所述，Avatar/Stats 每次渲染都是新类型，React 只能卸载重建。
• 数据耦合：通过闭包捕获父组件变量，使得子组件无法独立测试、无法复用、无法被 memo 稳定缓存，也失去了类型边界。

尤其注意：即使 Avatar 内部"恰好没有 state"，重挂载仍然会重建 DOM 节点并重新执行所有 effect——破坏性并不取决于子组件是否用了 useState。

正确写法：把数据放进行参，组件放回模块顶层

原文档给出的正确示例是把组件提升到模块顶层，通过显式 props 接收数据：

function Avatar({ src, theme }: { src: string; theme: string }) {
  return (
    <img
      src={src}
      className={theme === "dark" ? "avatar-dark" : "avatar-light"}
    />
  );
}

function Stats({ followers, posts }: { followers: number; posts: number }) {
  return (
    <div>
      <span>{followers} followers</span>
      <span>{posts} posts</span>
    </div>
  );
}

function UserProfile({ user, theme }) {
  return (
    <div>
      <Avatar src={user.avatarUrl} theme={theme} />
      <Stats followers={user.followers} posts={user.posts} />
    </div>
  );
}

这里有三层改进值得展开：

1. 身份稳定：Avatar、Stats 只被声明一次（模块加载时），此后每次渲染引用的都是同一个函数对象，React 可以稳定地复用实例，state、DOM、effect 全部保留。
2. 显式契约：props 成为子组件的唯一输入，Avatar 不再依赖闭包中的 user 与 theme，类型标注（{ src: string; theme: string }）让数据流一目了然，便于后续用 memo() 做按需缓存（见 rules/rerender-memo.md）。
3. 只传所需：UserProfile 传给 Stats 的是 followers/posts 两个标量而非整个 user 对象，缩小了父组件更新时子组件需要感知的数据面，配合 memo 时命中率更高。

原文档给出的结论非常明确：开发者把组件定义在内部，最常见的动机是"不传 props 就能访问父变量"；而正确的做法永远是显式传 props。

典型症状：如何在一线代码里识别这个 bug

原文档列出的四条症状，正是"每次渲染整树重挂载"在真实交互中的直接体现：

症状	成因解释
输入框每次按键都失焦	输入框随重挂载被销毁重建，焦点随之丢失，用户无法连续输入
动画意外重启	重挂载后 DOM 重建，CSS 动画/Web Animation 从头开始播放
useEffect 的清理/setup 在每次父渲染时都执行	effect 生命周期与实例绑定，实例被替换就会走一遍完整的 cleanup→setup
组件内部滚动位置被重置	滚动容器随 DOM 重建回到初始位置

在 ZCode 前端（packages/ui）中，这些症状最容易出现在高频更新的任务列表、输入框、弹窗与拖拽区域。如果某个组件出现"轻微交互却频繁闪烁/失焦/动画重启"且找不到 state 原因，优先检查是否在 JSX 的父函数体内定义了子组件或 render 辅助函数。

仓库实践佐证：模块顶层定义的正确范式

ZCode 仓库自身的组件代码正是这条规则的正面范例。以 TaskTitleOverflowText.tsx 为例，该组件实现了任务标题溢出检测与走马灯滚动，内部包含多处需要在渲染间保持稳定的资源，而它们全部被放在模块顶层而非组件函数体内：

• 模块级常量：marqueeGapPx、marqueePixelsPerSecond、minimumMarqueeDurationSeconds、mask 样式字符串等（见 TaskTitleOverflowText.tsx#L10-L21）；
• 模块级工具函数：createMaskKeyframe（见 TaskTitleOverflowText.tsx#L23-L25）；
• 组件本身以具名函数 export function TaskTitleOverflowText(...) 定义在顶层（见 TaskTitleOverflowText.tsx#L31）。

这样，即使父级任务列表行（task row）高频重渲染，TaskTitleOverflowText 的类型与辅助资源都保持稳定引用，动画对象（trackAnimation/maskAnimation）可以在 effect 内被正确地创建与取消（见 TaskTitleOverflowText.tsx#L141-L167），而不会因为每次渲染都拿到"新类型"而被迫重挂载。这也印证了规则库的工程取向：稳定的组件身份是 effect 正确性、动画连续性与状态保留的前提。

与相关规则的协同：构建完整的重渲染防护

"不在组件内定义组件"只是重渲染优化类别中的一条。将它与其他规则配合，可以形成完整的防护闭环（规则全表见 SKILL.md 与汇总文档 AGENTS.md）：

• rerender-memo（rules/rerender-memo.md）：把昂贵子组件提取到顶层并用 memo() 包裹，配合 props 不变性跳过无谓重渲染——前提正是本规则保证的"组件类型稳定"，否则 memo 也无法生效。
• rendering-hoist-jsx（rules/rendering-hoist-jsx.md）：把静态 JSX（如骨架屏、大型 SVG）提升到组件外复用同一元素，避免每次渲染重新创建元素。它与本规则同属"把不该在渲染期重建的东西移到外面"的思路，只是粒度不同（元素 vs 组件）。
• rerender-move-effect-to-event / rerender-defer-reads 等同类别规则：进一步缩小每次渲染的波及范围，让"保留实例、只更新必要的部分"成为常态。

需要说明的是，规则文件（rerender-memo.md 与 rendering-hoist-jsx.md）的注释都提到：如果项目启用了 React Compiler，编译器会自动完成部分 memo 化与静态 JSX 提升，手动优化可以相应减少。但"组件类型必须稳定"这一基线无论如何都不应被破坏——它同时是 React 渲染模型、effect 语义与可维护性的共同要求，不依赖任何编译期优化。

自查清单：快速修复指南

针对这条规则，可以在 Code Review 与重构时按以下步骤自查：

1. 定位：搜索组件函数体内（return 之前的 JSX 之外）是否出现 const Xxx = () => (...), function Xxx() {} 或 render 辅助函数定义。
2. 确认触发面：该父组件是否处于高频渲染路径（输入、列表项、hover、拖拽、订阅状态变化）；若是，重挂载代价会被放大。
3. 重构：将内部定义移动到模块顶层，把闭包中捕获的父变量改为显式 props；数据面较大时按需拆分（如示例中的 followers/posts）。
4. 验证：修复后确认输入焦点、动画连续性、effect 执行次数与滚动位置恢复正常；若组件内含 useState/useEffect，可临时加计数日志对比修复前后的 effect 触发次数。
5. 守住基线：后续新增代码遵循同一约定——组件定义只出现在模块顶层，父子通信一律走 props。

结语

"不要在组件内定义组件"这条规则，本质上是把 React 渲染模型的一条底层约束翻译成了可执行的编码规范：组件类型必须稳定，数据必须显式传递。它来自 ZCode 仓库内置的 Vercel 工程实践规则集（来源元数据见 metadata.json），并被标记为 HIGH 影响等级——因为"每次渲染整树重挂载"带来的，不只是性能损耗，还有失焦、动画错乱、effect 失控等一系列难以排查的交互缺陷。掌握并应用这条规则，是写出可预测、可优化、可维护的 React 组件的基础一步。