React Doctor：Hook 依赖遗漏与副作用逃逸的静态检测工程实践

在 AI 辅助编程日益普及的今天，LLM 生成的 React 代码质量参差不齐，其中 Hook 依赖遗漏与副作用逃逸是两类最具破坏力的模式缺陷。前者导致闭包陈旧、数据不同步，后者将业务逻辑混入渲染链路、引发不可预期的重渲染循环。传统 ESLint 配置对这类 React 特定模式的覆盖深度有限，React Doctor 作为专注 React 代码健康的静态分析工具，在 State & Effects 分类下提供了 9 条针对性规则，构建起从依赖完整性到副作用边界的完整检测体系。本文聚焦这两类错误模式，解析其检测原理与可落地参数。

Hook 依赖遗漏的危害链条

useEffect 的依赖数组是 React 渲染与副作用同步的核心契约。当 LLM 生成代码时，最常见的失误是遗漏依赖项或在依赖数组中引入非稳定引用，两者都会破坏组件状态的一致性。

遗漏依赖项的直接后果是闭包陈旧。组件在 props 或 state 变化后，useEffect 内的回调函数仍捕获的是上一次渲染的值，导致数据不同步。在异步数据获取场景中，这种问题尤为隐蔽 ——effect 内的 fetch 请求完成时，组件可能已经 unmount，或者引用的 state 值已经过期。更严重的是，当多个 effect 之间存在隐式数据依赖时，遗漏一个依赖项可能在生产环境中引发间歇性 bug，这类 bug 往往无法在开发环境复现。

依赖数组中引入非稳定引用是另一类高频问题。当开发者将新创建的对象字面量、数组或内联函数作为依赖项传入时，每次渲染都会生成新的引用，导致 effect 无限循环执行。这类问题在 AI 生成代码中尤为常见，因为模型倾向于在 JSX 内直接定义事件处理器或将 props 解构为局部变量后直接使用，而没有意识到这些操作会引入不稳定的引用。

副作用逃逸的典型模式

副作用逃逸指本应在 effect 内部处理或通过事件处理器触发的逻辑，错误地被放置在渲染阶段执行或通过状态变更间接触发，从而破坏 React 的单向数据流。

最典型的副作用逃逸是用 useEffect 模拟事件处理器。AI 在生成代码时，有时会误用 useEffect 来响应某个值的变化并更新另一个状态，而不是直接在该值变化的位置调用处理函数。这种模式将同步的渲染链路打断为异步的 effect 链，增加了状态更新的不可预测性。此外，在 effect 内调用三次以上的 setState 是级联状态更新的典型标志 —— 每次 setState 都会触发一次重渲染，多个 effect 之间的级联更新可能导致渲染链路振荡。

从 props 派生 state 是另一种常见的副作用逃逸。当组件用 useState 从 props 初始化值后，在 useEffect 内同步该值的变化时，实际上创建了一个派生状态，而这个派生状态本应通过 useMemo 在渲染阶段直接计算得出。派生 state 会导致不必要的重渲染，并且在 props 快速变化时可能产生状态滞后的现象。

React Doctor 核心检测规则

React Doctor 在 State & Effects 分类下提供了 9 条规则，针对上述问题构建了完整的检测网络。

react-doctor/rerender-dependencies 是检测依赖遗漏的第一道防线。这条规则的 severity 为 error，核心职责是捕获依赖数组中的新对象或新数组引用。当检测到依赖项是一个在组件渲染时重新创建的对象或数组字面量时，规则立即触发错误。这一规则对应的是 “依赖数组中引入非稳定引用” 问题，通过静态分析依赖项的 AST 节点类型来判断是否为字面量构造。

react-doctor/no-derived-state-effect 检测从 props 派生 state 的错误模式。当 useEffect 的唯一作用是根据某个 props 字段计算并设置 state 时，这条 error 级别的规则会触发。规则的检测逻辑是：识别 effect 体内只有单个 setState 调用，且该 setState 的值是从 props 派生计算而来。这条规则直接指向上文提到的副作用逃逸类型，强制开发者将派生逻辑前移至渲染阶段或使用 useMemo 缓存。

react-doctor/no-effect-event-handler 针对用 useEffect 模拟事件处理器的反模式进行了专项检测。这条 warn 级别的规则识别 effect 体内仅在响应特定值变化时执行状态更新，而没有进行真正的副作用操作（如数据获取、DOM 操作、全局状态订阅）。当检测到这种模式时，规则会建议将逻辑迁移至对应的事件处理器或直接在使用处调用处理函数。

react-doctor/no-cascading-set-state 对级联状态更新进行了限制。当单个 useEffect 内出现三次或以上的 setState 调用时，这条 warn 级别的规则会触发。规则的阈值设定为 3 次，这是一个经过平衡的参数 —— 既能够捕获真正的级联问题，又不会过度触发而干扰正常的状态更新逻辑。开发者可以将多个相关状态合并为 useReducer，或者将状态更新逻辑拆分至多个独立 effect 以避免单点过度集中。

react-doctor/no-derived-useState 检测 useState 从 props 初始化的反模式。当 useState 的初始值直接来自 props 变量时，这条 warn 规则会触发。这个初始值在后续渲染中不会自动同步 props 的变化，导致组件行为与预期不符。正确的做法是在渲染阶段直接使用 props，或通过 useMemo 在需要处计算派生值。

react-doctor/no-fetch-in-effect 检测在 useEffect 内部直接使用 fetch API 的问题。这条 error 规则禁止在 effect 中直接调用 fetch，推荐使用数据获取库（如 TanStack Query、SWR）或自定义的异步数据管理方案。fetch 在 effect 内直接使用会导致竞态条件、缺乏请求取消机制、缺少缓存与重试逻辑，这些问题在生产环境中会造成严重的用户体验问题。

评分机制与阈值设计

React Doctor 的健康评分公式为：100 - (unique_error_rules x 1.5) - (unique_warning_rules x 0.75)。这个公式以唯一触发的规则类型计分，而非问题实例数量。这意味着修复 49 处遗漏依赖与修复 1 处遗漏依赖对分数的影响相同 —— 只有彻底消除某类错误模式才能获得对应分值。这一设计鼓励开发者系统性解决一类问题，而非零散修补实例。

评分区间划分为三个等级：75 分以上为 Great，50 到 74 分为 Needs work，50 分以下为 Critical。error 级别的问题对分数的惩罚是 warning 级别的两倍，这种不对等权重确保了正确性问题的优先级高于性能问题。在 CI 场景中，可以通过 --fail-on warning 参数将 warning 也纳入构建失败条件，确保代码质量门槛不会随时间降低。

集成与配置策略

在 AI 生成代码的审查流程中，建议将 React Doctor 集成至预提交钩子与 PR 检查链路。使用 --staged 参数扫描仅暂存的文件，可以在代码合并前捕获 AI 生成的低质量模式。使用 --json 参数输出结构化报告，便于在自动化流程中解析与告警。

配置文件中的 ignore.overrides 提供了细粒度的规则豁免机制。对于某些需要特殊处理的文件，可以按 Glob 模式匹配后对特定规则进行屏蔽，而不影响其他文件的扫描覆盖。这种配置方式确保了规则体系的灵活性，同时保持了全局质量门槛的有效性。

在自定义规则方面，React Doctor 支持通过 eslint-plugin-react-hooks 的可选集成来增强依赖检测能力。当项目中检测到 React Compiler 时，eslint-plugin-react-hooks 的规则会自动启用，为使用 Babel 编译转换的项目提供额外的正确性保障。对于 effects-as-anti-pattern 检测，eslint-plugin-react-you-might-not-need-an-effect 插件提供了互补的规则集，包括 no-derived-state、no-chain-state-updates、no-event-handler 等规则，可以在 React Doctor 原生规则之外提供补充覆盖。

实践建议

针对 AI 生成代码的常见缺陷模式，建议在项目初始化时执行一次完整扫描，了解当前代码库的健康基线。根据扫描结果配置忽略规则时，优先使用 ignore.overrides 对特定文件的特定规则进行豁免，而非使用 ignore.files 批量忽略整个文件的扫描覆盖。后者会导致该文件完全脱离质量管控，存在引入其他缺陷的风险。

在日常开发中，建议将 React Doctor 的规则文档作为 AI agent 的系统提示词补充。通过 npx react-doctor@latest install 安装的 agent 规则文件会将 React 最佳实践嵌入到 AI 的生成决策中，从源头减少低质量代码的产生。这种预防性策略比事后检测更具成本效益，能够显著降低代码审查与重构的负担。

资料来源：React Doctor 官方仓库（https://github.com/millionco/react-doctor）及其规则文档（https://mintlify.wiki/millionco/react-doctor/rules/overview）。

ai-systems