内容
# React 调试工具 — Chrome DevTools 扩展
[](https://github.com/hoainho/react-debugger-extension/stargazers)
[](https://www.npmjs.com/package/@nhonh/react-debugger)
[](https://www.npmjs.com/package/@nhonh/react-debugger)
[](./LICENSE)
[](https://github.com/hoainho/react-debugger-extension/actions/workflows/ci.yml)
[](https://deepwiki.com/hoainho/react-debugger-extension)
> **唯一将 React 时间线 + 性能 + 内存 + 副作用 + Redux + CLS + AI 分析统一到单个 DevTools 标签的 Chrome 扩展 — 在您的应用中无需安装。**
**扩展版本：** 3.0.0 · **CLI 版本：** 2.1.2 · **作者：** [NhoNH](https://github.com/hoainho) · **许可证：** MIT
## ⚡ 30 秒试用
```bash
npx @nhonh/react-debugger@latest
```
然后将构建的扩展程序作为解压包加载到 `chrome://extensions` 中。 _Chrome 网上应用商店列表即将推出 — `npx` 是今天最快捷的方式。_
## 演示
---
## 为什么使用这个扩展
如果您今天在生产环境中调试 React 应用，您可能正在使用四种工具来追踪一个错误：
- **[React DevTools](https://github.com/facebook/react)** — 组件树，但没有时间线，没有 CLS，没有内存泄漏检测
- **Chrome 性能标签** — 渲染，但没有 React 上下文
- **[Redux DevTools](https://github.com/reduxjs/redux-devtools)** — 状态，但与渲染周期隔离
- **[react-scan](https://github.com/aidenybai/react-scan)** — 优秀的渲染叠加层，但需要应用代码更改；没有 Redux，没有 CLS，没有内存
- **[why-did-you-render](https://github.com/welldone-software/why-did-you-render)** — 精确的渲染日志，但仅限控制台，需要 Babel 配置
**React Debugger 将所有这些统一到一个 DevTools 标签中** — 在您的应用中无需代码更改，包含七个分析器和一个可选的 AI 层，用于安全/性能/崩溃洞察。
**可防御的三重锁定** 竞争对手无法组合： **CLS 叠加层 + `useEffect` 审计 + AI 分析** ，所有这些都在一个无需安装的浏览器面板中。
## 功能
| 标签 | 功能 |
|---|---|
| **时间线** | 每次渲染、状态更改、效果和错误的视觉历史记录 |
| **UI 和状态** | 检测直接状态突变、缺少键、`index` 作为键、过时闭包 |
| **性能** | 渲染次数、渲染原因（属性/状态/上下文）、核心 Web 重要性叠加层 |
| **内存** | 堆大小火花图、增长率警报、泄漏检测启发式 |
| **副作用** | `useEffect` 审计：缺少清理、错误的依赖数组 |
| **CLS** | 实时累积布局偏移得分 + 按元素归因 |
| **Redux** | 状态树、操作历史、手动操作调度（无需单独的 Redux DevTools） |
| **AI 分析** | LLM 驱动的安全性、性能和崩溃风险扫描。每个会话 3 次免费分析；使用订阅密钥无限分析。无需您的 API 密钥。 |
## 截图
| 时间线 | 性能 |
|---|---|
|  |  |
| 内存 | 副作用 |
|---|---|
|  |  |
| CLS | Redux |
|---|---|
|  |  |
## 比较
| 功能 | **React Debugger** | react-devtools | react-scan | why-did-you-render | redux-devtools |
|---|:---:|:---:|:---:|:---:|:---:|
| 渲染时间线（环境） | ✅ | ⚠️（手动记录） | ⚠️ 仅叠加层 | ❌ | ❌ |
| 渲染原因（属性/状态差异） | ✅ | ⚠️（无值） | ✅ | ✅ 控制台 | ❌ |
| **内存泄漏检测** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **`useEffect` 审计** | ✅ | ❌ | ❌ | ❌ | ❌ |
| Redux 集成 | ✅ | ❌ | ❌ | ⚠️ | ✅ 时间旅行 |
| **CLS 叠加层** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **AI 分析** | ✅ | ❌ | ❌ | ❌ | ❌ |
| 安装方法 | Chrome 扩展程序（无需应用更改） | Chrome 扩展程序 | npm/脚本标签（应用代码） | npm + Babel | Chrome 扩展程序 |
**粗体行** = 其他工具无法组合的功能。
### 最近发布：v3.0.0 — DevTools 原生重新设计 + 8 个新检测器
自推出以来最大的发布 — 全新的 UI 重新设计、八个新问题检测器、一个 MCP 服务器和一个 BYOK AI：
- **DevTools 原生 UI 重新设计。** 9 个旧标签合并为一个专注的 5 视图外壳 — **仪表盘 / 分析器 / 状态 / 效果 / 设置** — 带有活动下划线导航、每个视图的计数徽章、分段子标签和粘性标题。经典的 9 标签布局保持在一个切换之下。
- **新仪表盘。** 一个首屏概览：严重性 KPI 统计瓷砖、React 版本/模式 + Redux 芯片、渲染压力火花图、顶部罪犯组件和页面加载重要性指标。
- **图表。** 一个独立于依赖关系的 `ChartCanvas` （区域/线/条形 + 淡网格 + 强调端点）为内存随时间变化的时间线和性能渲染分布提供支持。
- **8 个新检测器** 在一个可插拔的注册表中（每个检测器的设置切换 + 置信度徽章）：4 个主要 — **不稳定的列表键** 、 **水合不匹配** 、 **上下文级联** 、 **悬念瀑布** — 加上 **过时闭包异步** 、 **内联处理程序成本** 和 **渲染期间引用突变** 。
- **MCP 服务器** 用于 LLM 编码代理（stdio 桥 + token/Origin 配对）和 **BYOK AI 提供商** （托管代理 / OpenAI / Anthropic / 无），具有可选的匿名遥测（默认为 **关闭** ）。
- **无障碍和质量。** WCAG 2.1 AA 对比度、`prefers-reduced-motion` 、焦点可见环和一个无头 Playwright 视觉回归通道。
参见 [CHANGELOG.md](./CHANGELOG.md) 以获取完整的历史记录（包括在此基础上构建的 v2.0.3 零延迟性能工作）。
---
## 安装
### 选项 1 — 通过 npx 快速安装（推荐）
```bash
npx @nhonh/react-debugger
```
这将下载并提取最新扩展程序到您的当前目录。然后在 Chrome 中加载它：
1. 打开 `chrome://extensions/`
2. 启用 **开发者模式** （右上角）
3. 点击 **加载解压**
4. 选择提取的文件夹
### 选项 2 — 从源代码构建
您需要 **Node 20+** 和 **Chrome 122+** 。
```bash
git clone https://github.com/hoainho/react-debugger-extension.git
cd react-debugger-extension
npm ci
npm run build
```
然后通过相同的 `chrome://extensions/` → **加载解压** 流程将 `dist/` 文件夹加载到 Chrome 中。
### 选项 3 — 从版本下载 ZIP
1. 从 [GitHub 版本](https://github.com/hoainho/react-debugger-extension/releases/latest) 获取 `react-debugger.zip`
2. 解压并通过 `chrome://extensions/` → **加载解压** 加载
---
## 快速入门
1. 打开任何 React 16+ 应用
2. 按 `F12` （或 `Cmd+Option+I` / `Ctrl+Shift+I` ）
3. 在 DevTools 面板条中找到 **"React Debugger"** 标签
4. 扩展程序自动检测 React 并立即开始收集数据
有关每个标签的详细演练、按技能级别划分的调试策略和阈值参考表，请参见 **[DEBUGGING-GUIDE.md](./DEBUGGING-GUIDE.md)**。
有关 6 个类别（初始化、性能监控、Redux 集成、内存和清理、UI 和状态、CLS 和布局）中 50 个记录的边缘案例，请参见 **[EDGE-CASES.md](./EDGE-CASES.md)**。
---
## 比较
| | React Debugger | React DevTools | why-did-you-render | react-scan |
|---|:---:|:---:|:---:|:---:|
| 组件树 | 部分 | ✅ | — | ✅ |
| 渲染跟踪 | ✅ | ✅ 分析器 | ✅ | ✅ |
| 内存配置文件 | ✅ | — | — | — |
| 副作用审计 | ✅ | — | 部分 | — |
| Redux 状态 | ✅ | — | — | — |
| CLS 监控 | ✅ | — | — | — |
| AI 分析 | ✅ | — | — | — |
| 在 DevTools 面板中 | ✅ | ✅ | — | — |
**楔形：** React Debugger 是唯一一个在单个标签中组合所有七个分析器的 Chrome DevTools 面板。
---
## 开发
```bash
npm ci # 一次性安装
npm run dev # 重新构建（监视模式）
npm run build # 生产构建 → dist/
npm run test:run # 一次性 Vitest 运行
npm run package # 构建 + zip → react-debugger.zip
```
每次开发重新构建后，点击 `chrome://extensions/` 中的扩展程序卡片上的刷新图标，然后重新加载被检查的页面。
### 项目结构
```
react-debugger-extension/
├── src/
│ ├── background/ # 服务工作线程
│ ├── content/ # 内容脚本（CLS 监控）
│ ├── inject/ # 页面脚本（React 纤维钩子，bippy-aligned）
│ ├── devtools/ # DevTools 页面入口
│ ├── panel/
│ │ ├── components/ # 可重用组件
│ │ ├── tabs/ # 8 个标签组件，包括 AI 分析
│ │ └── styles/ # CSS（支持 prefers-reduced-motion）
│ ├── services/ # AI 客户端，令牌优化器，快照构建器
│ ├── types/ # TypeScript 类型
│ ├── utils/ # 实用程序（清理，消息传递）
│ └── __tests__/ # Vitest 单元测试（9 个文件中的 170 个测试）
├── cli/ # @nhonh/react-debugger npm 包
├── worker/ # Cloudflare Worker（AI 订阅密钥验证）
├── test/
│ └── fixtures/basic/ # Playwright 的 E2E 固定装置应用（Vite + React 18）
├── docs/ # 目标页面（hoainho.github.io/react-debugger-extension）
└── openspec/ # 飞行中的设计提案（增长活动，MCP 服务器 v1）
```
---
## 故障排除
### 扩展程序未在 DevTools 中显示
1. 验证您是否加载了 `dist/` 文件夹，而不是存储库根目录
2. 在加载扩展程序后重新加载被检查的页面
3. 在 `chrome://extensions/` 中检查错误
### 未检测到 React
- 页面必须使用具有 Fiber 架构的 React 16+
- 刷新页面 — 内容脚本在 `document_start` 处附加
- 在控制台中检查扩展程序的错误
- React 必须处于开发模式才能使用某些功能（例如，渲染原因）
### 未检测到问题
- 扩展程序仅在发现问题时才会显示问题 — 空面板表示应用健康
- 尝试 [DEBUGGING-GUIDE.md](./DEBUGGING-GUIDE.md) 中的示例
### 主页面的性能回归
v2.0.3 专门针对主机页面延迟。如果您仍然看到它，请 [打开一个错误](https://github.com/hoainho/react-debugger-extension/issues/new?template=bug_report.yml) ，并附上 Chrome 版本、扩展程序版本和被检查的页面 URL。
---
## 贡献
我们欢迎各种规模的贡献。最快捷的方式：
1. 浏览 [good-first-issue 项](https://github.com/hoainho/react-debugger-extension/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — 每个问题都有范围、文件指针和验收标准
2. 用评论认领：`@hoainho 我将处理这个问题`
3. 阅读 **[CONTRIBUTING.md](./.github/CONTRIBUTING.md)** 以获取本地设置、约定提交和 PR 审查 SLA
我们还有 [`help wanted` 项](https://github.com/hoainho/react-debugger-extension/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) 以获取更大的贡献。
### 社区
- 💬 [GitHub 讨论](https://github.com/hoainho/react-debugger-extension/discussions) — 问题、想法、展示和讲述。五个类别，带有结构化模板： [Q&A](https://github.com/hoainho/react-debugger-extension/discussions/categories/q-a) 、 [想法](https://github.com/hoainho/react-debugger-extension/discussions/categories/ideas) 、 [展示和讲述](https://github.com/hoainho/react-debugger-extension/discussions/categories/show-and-tell) 、 [常规](https://github.com/hoainho/react-debugger-extension/discussions/categories/general) 、 [公告](https://github.com/hoainho/react-debugger-extension/discussions/categories/announcements) 。
- 📚 [Wiki](https://github.com/hoainho/react-debugger-extension/wiki) — 活动文档：架构概述、FAQ、调试食谱、词汇表
- 🐛 [问题](https://github.com/hoainho/react-debugger-extension/issues) — 错误报告、功能请求
- 🔒 [安全策略](./SECURITY.md) — 责任披露（90 天时间线）
- 📜 [行为准则](./.github/CODE_OF_CONDUCT.md) — 贡献者契约 v2.1
---
## 下一步
活跃的设计工作位于 [openspec/changes/](./openspec/changes/) 中：
- **`mcp-server-v1/`** — 添加一个模型上下文协议服务器，以便 LLM 编码代理（Claude Desktop、opencode、Cursor）可以以编程方式驱动扩展程序的调试工具。目前处于规范阶段；第一个贡献者 PR 已经交付了脚手架。
- **`growth-and-contributor-attraction/`** — 90 天计划，以增长项目和贡献者群体。第一周（许可 + 入门）已于 2026 年 5 月交付。
---
## ⭐ 如果这为您节省了时间，请给存储库加星
每个星星都帮助更多的 React 开发人员发现该项目 — 这是您向维护者发送的最有用的信号，表明这项工作很重要。 **一次点击。巨大的差异。**
[](https://star-history.com/#hoainho/react-debugger-extension&Date)
您也可以 [👀 关注版本](https://github.com/hoainho/react-debugger-extension/subscription) 以在新标签（或 MCP 服务器）发布时收到通知。
## 许可证
[MIT](./LICENSE) — 版权所有 © 2025-2026 NhoNH。
> React 和 React 徽标是 Meta Platforms, Inc. 的商标。本扩展程序不隶属于或得到 Meta 或 React 团队的认可。
