@linhey/react-debug-inspector 🎯

一个轻量级的 React 调试辅助工具，让你在浏览器中直接识别组件、标签及其对应的源码行号。

🎬 演示

在线演示

🌐 在线体验 Demo

GitHub Pages 配置说明见 GITHUB_PAGES.md

快速预览

1. 点击右下角的 🎯 按钮进入检查模式
2. 鼠标悬停在任何元素上查看调试信息
3. 直接点击元素复制完整的调试标识
4. 使用悬浮菜单复制文案、图片或全部上下文
5. 按 Esc 键退出检查模式

特性

• 🚀 零配置注入：通过 Babel 插件自动为每个 JSX 元素添加 data-debug 属性。
• 🎯 瞄准模式：悬浮显示元素标识，单击一键复制。
• 🧾 上下文复制：支持复制目标文案、图片信息和完整调试上下文。
• 📁 完整路径：显示文件路径、组件名、标签名和行号，精确定位源码。
• 🌳 零污染：生产环境构建时自动剔除，不增加包体积。
• ⌨️ 快捷键支持：支持 Esc 退出及 Alt+右键 快速复制。

安装

npm install @linhey/react-debug-inspector --save-dev

使用方法

1. 配置 Vite (vite.config.ts)

推荐在 Vite 8+ 使用官方导出的插件工厂，确保 data-debug 注入稳定：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { createViteDebugInspectorPlugin } from '@linhey/react-debug-inspector';

export default defineConfig({
  plugins: [
    createViteDebugInspectorPlugin(),
    react(),
  ],
});

如果你仍在旧链路中使用 Babel 直接注入，也可以保留：

import debugInspector from '@linhey/react-debug-inspector';

react({
  babel: {
    plugins: [debugInspector],
  }
})

2. 初始化交互界面 (main.tsx)

import { initInspector } from '@linhey/react-debug-inspector';

if (import.meta.env.DEV) {
  initInspector();
}

交互说明

• 🎯 按钮：位于右下角，点击进入/退出审查模式。
• 悬浮模式：进入模式后，鼠标指向的元素将被高亮，并显示 文件名 › 组件 › 标签:行号。
• 悬浮菜单：命中元素后可使用“复制 ID / 复制文案 / 复制图片 / 全部复制”。
• 单击左键：复制完整标识（文件路径:组件:标签:行号）到剪贴板并退出。
• 复制图片：优先尝试写入图片本体；若浏览器或资源不支持，则自动降级复制图片信息文本。
• Esc：退出模式。
• Alt + 右键：非模式下亦可直接复制标识。

输出格式

复制到剪贴板的格式为：src/components/Button.tsx:Button:button:42

• src/components/Button.tsx - 文件相对路径
• Button - 组件名
• button - HTML 标签名
• 42 - 源码行号

开发

# 安装依赖
npm install

# 运行单元测试
npm test

# 运行 E2E 测试
npm run test:e2e

# 录制演示视频（选择元素 -> 粘贴到输入框）
npm run record:demo

# 运行所有测试
npm run test:all

# 构建
npm run build

# 开发模式
npm run dev

发布

本项目使用 GitHub Actions 自动化发布流程。详见 GITHUB_ACTIONS.md。

快速发布

1. 进入 GitHub Actions 页面
2. 选择 "Version Bump and Release" 工作流
3. 点击 "Run workflow"，选择版本类型（patch/minor/major）
4. 自动完成测试、构建、发布到 NPM

License

MIT