使用 React Doctor 扫描 React 代码中的反模式

React 应用程序很少会一次性崩溃。它们是逐渐退化的——这里多了一个不必要的 useEffect,那里多了几层额外的属性传递(prop drilling),还有一个可访问性属性悄悄地缺失了。当这些问题在生产环境中暴露出来时,修复它们的成本已经很高了。

React Doctor 是一个开源的 CLI 工具,专门用于在这些问题累积之前捕获它们。运行一条命令,获得 0-100 的代码健康评分,并收到针对整个代码库的可操作诊断结果。

React Doctor 实际做什么(以及不做什么)

React Doctor 是一个静态分析工具,而不是运行时分析器。它不测量渲染时间,也不跟踪实时应用中的组件重新渲染。相反,它读取你的源代码,并在你运行应用程序之前识别结构性问题。

这个区别很重要。像 React DevTools Profiler 这样的工具会显示运行时的性能瓶颈。React Doctor 则显示为什么你的代码在结构上是脆弱的——使重构变得痛苦的属性传递、不应该存在的副作用、使打包体积膨胀的死代码导出,以及影响真实用户的可访问性违规。

它也不仅仅是一个代码检查工具。像 ESLint 这样的工具捕获语法问题并强制执行样式规则。React Doctor 通过扫描架构、打包体积、安全性、死代码和框架特定模式等类别来分析更广泛的项目健康状况。它会自动检测你的框架和 React 配置,然后激活相关规则。

如何在 30 秒内扫描你的 React 项目

无需安装。导航到项目根目录并运行:

npx -y react-doctor@latest .

添加 --verbose 参数可查看每个问题的确切文件路径和行号:

npx -y react-doctor@latest . --verbose

React Doctor 并行运行两个过程:对激活规则的代码检查过程,以及标记未使用文件、导出、类型和重复项的死代码检查过程。结果按严重程度评分——错误的权重高于警告——最终产生健康评分:75+ 为优秀,50-74 为需要改进,50 以下为严重。

它发现的 React 反模式

以下是 React Doctor 通常识别的结构性问题类型:

不必要的 useEffect 使用 — 当状态派生发生在副作用中而不是在渲染期间时,你会遇到过时数据的 bug 和更难理解的逻辑。React 官方指南越来越建议在可能的情况下在渲染期间派生值,而不是依赖副作用。

深层属性传递 — 通过多个组件层传递属性是一个结构性警告信号。修复方法通常是使用 Context、组合或状态就近放置。

可能导致不稳定渲染的列表键 — 使用不稳定的标识符(如数组索引)可能在列表重新排序时导致细微的 UI bug。

重量级库导入 — 导入整个库会使打包体积膨胀。React Doctor 可以突出显示可以通过 React.lazy() 或框架工具(如 next/dynamic)进行代码分割的模式。

可访问性缺陷 — 图片上缺少 alt 属性或其他可访问性疏忽可能在开发过程中被忽略,但会影响真实用户。

源代码中的潜在密钥 — 静态扫描可以检测类似 API 密钥或提交到代码库的令牌的模式。

将 React Doctor 集成到团队工作流程中

对于团队来说,最有价值的集成是 GitHub Actions 工作流:

- uses: actions/checkout@v5
  with:
    fetch-depth: 0
- uses: millionco/react-doctor@main
  with:
    diff: main
    github-token: ${{ secrets.GITHUB_TOKEN }}

diff 选项仅扫描拉取请求中更改的文件,保持 CI 快速运行。当提供 github-token 时,发现的问题会直接作为 PR 评论发布——无需翻查日志。

对于 AI 辅助工作流程,你可以教授编码助手(如 Cursor 或 Claude Code)React Doctor 使用的 React 最佳实践规则:

curl -fsSL https://react.doctor/install-skill.sh | bash

这让你的助手可以使用 React Doctor 应用的相同规则集来诊断问题并提出修复建议。

真实世界的健康评分

React Doctor 已经在几个知名的开源 React 项目上运行过:

即使是成熟、维护良好的项目也有改进空间。这些问题会悄悄累积,而自动化扫描是尽早捕获它们的最简单方法之一。

结论

React Doctor 不能取代代码审查,但它消除了其中繁琐的部分。结构性问题、可访问性缺陷、死代码和安全风险会被自动捕获,因此人工审查者可以专注于逻辑和设计决策。

在你当前的项目上运行一次。你得到的评分将比一周的人工审查更能说明代码库的健康状况。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.