react-devtools-plus

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React DevTools Plus

Skill by ara.so — Devtools Skills collection.

React DevTools Plus is an open-source build tool plugin that provides visual debugging for React applications. It mirrors your React Fiber tree in real-time, profiles component renders, and offers a keyboard-first overlay—all with zero impact on production builds.

由ara.so开发的工具——Devtools Skills系列之一。

React DevTools Plus是一款开源构建工具插件，为React应用提供可视化调试功能。它能实时镜像你的React Fiber树、分析组件渲染性能，并提供优先支持键盘操作的浮层——且对生产构建完全无影响。

What It Does

功能特性

Fiber Tree Mirroring: Automatically instruments React Fiber roots to visualize component hierarchies
Timeline Profiling: Tracks component renders and performance metrics
Floating Overlay: Toggle with
```
Alt/Option + Shift + D
```
for inline debugging
Asset Inspection: Browse and inspect project assets (images, fonts, etc.)
Editor Integration: Click-to-open components in your IDE
React 16-19 Support: Works with React 16.8+, 17, 18, and 19
Dev-Only: Completely removed from production bundles

Fiber树镜像：自动检测React Fiber根节点，可视化组件层级结构
时间线性能分析：追踪组件渲染情况及性能指标
悬浮浮层：使用
```
Alt/Option + Shift + D
```
快捷键切换，支持内联调试
资源检查：浏览并检查项目资源（图片、字体等）
编辑器集成：点击即可在IDE中打开组件
React 16-19支持：兼容React 16.8+、17、18及19版本
仅开发环境可用：在生产打包中会被完全移除

Installation

安装

For Vite Projects

适用于Vite项目

bash

pnpm add -D react-devtools-plus

typescript

// vite.config.ts
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

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

bash

pnpm add -D react-devtools-plus

typescript

// vite.config.ts
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

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

For Webpack Projects

适用于Webpack项目

bash

npm install -D react-devtools-plus

javascript

// webpack.config.js
const { reactDevToolsPlus } = require('react-devtools-plus/webpack')

module.exports = {
  plugins: [
    reactDevToolsPlus(),
  ],
}

bash

npm install -D react-devtools-plus

javascript

// webpack.config.js
const { reactDevToolsPlus } = require('react-devtools-plus/webpack')

module.exports = {
  plugins: [
    reactDevToolsPlus(),
  ],
}

Configuration

配置

Basic Configuration

基础配置

typescript

// vite.config.ts
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    react(),
    reactDevToolsPlus({
      // Enable/disable overlay (default: true in dev mode)
      overlay: true,
      
      // Custom DevTools route (default: '/__react_devtools__')
      base: '/__react_devtools__',
      
      // Editor integration (auto-detected by default)
      launchEditor: 'code', // 'code' | 'webstorm' | 'cursor' | 'vim' | etc.
    }),
  ],
})

typescript

// vite.config.ts
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    react(),
    reactDevToolsPlus({
      // 启用/禁用浮层（默认：开发模式下为true）
      overlay: true,
      
      // 自定义DevTools路由（默认：'/__react_devtools__'）
      base: '/__react_devtools__',
      
      // 编辑器集成（默认自动检测）
      launchEditor: 'code', // 'code' | 'webstorm' | 'cursor' | 'vim' | 其他
    }),
  ],
})

Advanced Configuration

进阶配置

typescript

// vite.config.ts
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    react(),
    reactDevToolsPlus({
      // Disable overlay, use only the dedicated route
      overlay: false,
      
      // Custom base path
      base: '/__debug__',
      
      // Specific editor with custom launch command
      launchEditor: 'webstorm',
    }),
  ],
})

typescript

// vite.config.ts
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    react(),
    reactDevToolsPlus({
      // 禁用浮层，仅使用专属路由
      overlay: false,
      
      // 自定义基础路径
      base: '/__debug__',
      
      // 指定编辑器及自定义启动命令
      launchEditor: 'webstorm',
    }),
  ],
})

Webpack Configuration

Webpack配置

javascript

// webpack.config.js
const { reactDevToolsPlus } = require('react-devtools-plus/webpack')

module.exports = {
  mode: 'development',
  plugins: [
    reactDevToolsPlus({
      overlay: true,
      base: '/__react_devtools__',
      launchEditor: 'code',
    }),
  ],
}

javascript

// webpack.config.js
const { reactDevToolsPlus } = require('react-devtools-plus/webpack')

module.exports = {
  mode: 'development',
  plugins: [
    reactDevToolsPlus({
      overlay: true,
      base: '/__react_devtools__',
      launchEditor: 'code',
    }),
  ],
}

Usage Patterns

使用方式

Accessing DevTools

打开DevTools

Method 1: Keyboard Shortcut Press

Alt + Shift + D

(Windows/Linux) or

Option + Shift + D

(macOS) to toggle the floating overlay.

Method 2: Direct URL Navigate to

http://localhost:5173/__react_devtools__/

(adjust port/base as configured).

Method 3: Toggle Overlay Visibility Press

Alt + Shift + R

(Windows/Linux) or

Option + Shift + R

(macOS) to toggle overlay visibility.

Press

Escape

to close the overlay.

方法1：键盘快捷键 按下

Alt + Shift + D

（Windows/Linux）或

Option + Shift + D

（macOS）切换悬浮浮层。

方法2：直接访问URL 导航至

http://localhost:5173/__react_devtools__/

（根据配置调整端口和基础路径）。

方法3：切换浮层可见性 按下

Alt + Shift + R

（Windows/Linux）或

Option + Shift + R

（macOS）切换浮层可见性。

按下

Escape

关闭浮层。

Component Tree Inspection

组件树检查

Once DevTools is open:

View Component Hierarchy: The left panel shows your React component tree in real-time
Inspect Props/State: Click any component to view its props, state, and hooks
Open in Editor: Click the "Open in Editor" button to jump to source code
Search Components: Use the search bar to filter components by name

打开DevTools后：

查看组件层级：左侧面板实时展示React组件树
检查Props/State：点击任意组件查看其Props、State及Hooks
在编辑器中打开：点击“Open in Editor”按钮跳转至源代码
搜索组件：使用搜索框按名称筛选组件

Timeline Profiling

时间线性能分析

Switch to the Timeline tab
Click "Start Recording" to begin profiling
Interact with your app (trigger renders)
Click "Stop Recording" to analyze performance
Review render durations, commit phases, and component updates

切换至Timeline标签页
点击“Start Recording”开始分析
与应用交互（触发渲染）
点击“Stop Recording”分析性能
查看渲染时长、提交阶段及组件更新情况

Asset Inspection

资源检查

Switch to the Assets tab
Browse images, fonts, and other project assets
Click assets to view details and usage
Copy asset paths for use in your code

切换至Assets标签页
浏览图片、字体及其他项目资源
点击资源查看详情及使用情况
复制资源路径用于代码中

Real-World Examples

实战示例

Example 1: Next.js App with Vite

示例1：基于Vite的Next.js应用

typescript

// next.config.mjs (with Vite plugin via next-with-vite)
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    reactDevToolsPlus({
      overlay: true,
      base: '/__devtools__',
    }),
  ],
})

typescript

// next.config.mjs（通过next-with-vite使用Vite插件）
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    reactDevToolsPlus({
      overlay: true,
      base: '/__devtools__',
    }),
  ],
})

Example 2: React SPA with Custom Editor

示例2：自定义编辑器的React单页应用

typescript

// vite.config.ts
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    react(),
    reactDevToolsPlus({
      overlay: true,
      launchEditor: 'cursor', // Open components in Cursor AI
    }),
  ],
})

typescript

// vite.config.ts
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    react(),
    reactDevToolsPlus({
      overlay: true,
      launchEditor: 'cursor', // 在Cursor AI中打开组件
    }),
  ],
})

Example 3: Monorepo with Multiple React Apps

示例3：包含多个React应用的单体仓库

typescript

// apps/admin/vite.config.ts
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    reactDevToolsPlus({
      base: '/__admin_devtools__', // Unique base per app
    }),
  ],
})

// apps/customer/vite.config.ts
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    reactDevToolsPlus({
      base: '/__customer_devtools__', // Unique base per app
    }),
  ],
})

typescript

// apps/admin/vite.config.ts
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    reactDevToolsPlus({
      base: '/__admin_devtools__', // 每个应用使用唯一基础路径
    }),
  ],
})

// apps/customer/vite.config.ts
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig({
  plugins: [
    reactDevToolsPlus({
      base: '/__customer_devtools__', // 每个应用使用唯一基础路径
    }),
  ],
})

Example 4: Conditional DevTools (Environment-based)

示例4：基于环境的条件式DevTools

typescript

// vite.config.ts
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig(({ mode }) => ({
  plugins: [
    react(),
    // Only enable in development and staging
    (mode === 'development' || mode === 'staging') && reactDevToolsPlus({
      overlay: mode === 'development', // Overlay only in dev
      base: '/__devtools__',
    }),
  ].filter(Boolean),
}))

typescript

// vite.config.ts
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import { reactDevToolsPlus } from 'react-devtools-plus/vite'

export default defineConfig(({ mode }) => ({
  plugins: [
    react(),
    // 仅在开发和预发布环境启用
    (mode === 'development' || mode === 'staging') && reactDevToolsPlus({
      overlay: mode === 'development', // 仅在开发环境显示浮层
      base: '/__devtools__',
    }),
  ].filter(Boolean),
}))

Example 5: Webpack with React and TypeScript

示例5：结合React和TypeScript的Webpack项目

javascript

// webpack.config.js
const path = require('path')
const HtmlWebpackPlugin = require('html-webpack-plugin')
const { reactDevToolsPlus } = require('react-devtools-plus/webpack')

module.exports = {
  mode: 'development',
  entry: './src/index.tsx',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './public/index.html',
    }),
    reactDevToolsPlus({
      overlay: true,
      launchEditor: 'code',
    }),
  ],
  devServer: {
    port: 3000,
    hot: true,
  },
}

javascript

// webpack.config.js
const path = require('path')
const HtmlWebpackPlugin = require('html-webpack-plugin')
const { reactDevToolsPlus } = require('react-devtools-plus/webpack')

module.exports = {
  mode: 'development',
  entry: './src/index.tsx',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './public/index.html',
    }),
    reactDevToolsPlus({
      overlay: true,
      launchEditor: 'code',
    }),
  ],
  devServer: {
    port: 3000,
    hot: true,
  },
}

Key Features & API

核心特性与API

Plugin Options

插件选项

typescript

interface ReactDevToolsPlusOptions {
  /**
   * Enable/disable the floating overlay
   * @default true in development mode
   */
  overlay?: boolean

  /**
   * Custom base path for DevTools UI
   * @default '/__react_devtools__'
   */
  base?: string

  /**
   * Editor to launch when clicking "Open in Editor"
   * Auto-detected by default
   * @default auto-detected
   */
  launchEditor?: 'code' | 'webstorm' | 'cursor' | 'vim' | 'atom' | 'sublime' | string
}

typescript

interface ReactDevToolsPlusOptions {
  /**
   * 启用/禁用悬浮浮层
   * @default 开发模式下为true
   */
  overlay?: boolean

  /**
   * DevTools UI的自定义基础路径
   * @default '/__react_devtools__'
   */
  base?: string

  /**
   * 点击"Open in Editor"时启动的编辑器
   * 默认自动检测
   * @default 自动检测
   */
  launchEditor?: 'code' | 'webstorm' | 'cursor' | 'vim' | 'atom' | 'sublime' | string
}

Keyboard Shortcuts

键盘快捷键

Shortcut	Action
`Alt/Option + Shift + D`	Toggle DevTools overlay
`Alt/Option + Shift + R`	Toggle overlay visibility
`Escape`	Close overlay

快捷键	操作
`Alt/Option + Shift + D`	切换DevTools浮层
`Alt/Option + Shift + R`	切换浮层可见性
`Escape`	关闭浮层

DevTools UI Tabs

DevTools UI标签页

Component Tree: Real-time React Fiber tree visualization
Timeline: Render profiling and performance metrics
Assets: Project asset browser and inspector
Settings: DevTools configuration and preferences

Component Tree：实时React Fiber树可视化
Timeline：渲染性能分析及指标
Assets：项目资源浏览器与检查器
Settings：DevTools配置与偏好设置

Troubleshooting

故障排查

DevTools Not Appearing

DevTools未显示

Issue: Pressing the keyboard shortcut or navigating to the URL shows nothing.

Solutions:

Ensure you're running in development mode (
```
NODE_ENV=development
```
)
Check that the plugin is correctly added to your Vite/Webpack config
Verify your dev server is running and the port is correct
Check browser console for errors

问题：按下快捷键或访问URL后无任何显示。

解决方案:

确保处于开发模式（
```
NODE_ENV=development
```
）
检查插件是否正确添加至Vite/Webpack配置
验证开发服务器是否运行及端口是否正确
查看浏览器控制台是否有错误

Overlay Blocks UI Elements

浮层遮挡UI元素

Issue: The floating overlay is interfering with app interaction.

Solutions:

typescript

// Disable overlay, use dedicated route only
reactDevToolsPlus({
  overlay: false,
})

Or toggle visibility with

Alt/Option + Shift + R

问题：悬浮浮层影响应用交互。

解决方案:

typescript

// 禁用浮层，仅使用专属路由
reactDevToolsPlus({
  overlay: false,
})

或使用

Alt/Option + Shift + R

切换可见性。

"Open in Editor" Not Working

"Open in Editor"功能失效

Issue: Clicking components doesn't open them in your editor.

Solutions:

typescript

// Explicitly specify your editor
reactDevToolsPlus({
  launchEditor: 'code', // or 'cursor', 'webstorm', etc.
})

Ensure your editor's command-line tool is installed:

VS Code: Install
```
code
```
command via Command Palette → "Shell Command: Install 'code' command in PATH"
Cursor: Similar to VS Code
WebStorm: Ensure
```
webstorm
```
command is in PATH

问题：点击组件无法在编辑器中打开。

解决方案:

typescript

// 明确指定编辑器
reactDevToolsPlus({
  launchEditor: 'code', // 或'cursor'、'webstorm'等
})

确保编辑器的命令行工具已安装：

VS Code：通过命令面板 → "Shell Command: Install 'code' command in PATH"安装
```
code
```
命令
Cursor：与VS Code操作类似
WebStorm：确保
```
webstorm
```
命令已加入PATH

Components Not Showing in Tree

组件未在树中显示

Issue: Some components are missing from the DevTools tree.

Solutions:

Ensure you're using React 16.8+ (Hooks required)
Check that components are mounted and rendered
Verify React DevTools is instrumenting Fiber roots (check console for initialization logs)
Try refreshing the DevTools panel

问题：部分组件未出现在DevTools树中。

解决方案:

确保使用React 16.8+（需支持Hooks）
检查组件是否已挂载并渲染
验证React DevTools是否已检测Fiber根节点（查看控制台初始化日志）
尝试刷新DevTools面板

DevTools Affecting Production Build

DevTools影响生产构建

Issue: DevTools code appears in production bundle.

Solutions: The plugin should automatically exclude itself from production builds. Verify:

typescript

// vite.config.ts
export default defineConfig(({ mode }) => ({
  plugins: [
    react(),
    // Plugin is dev-only by default
    reactDevToolsPlus(),
  ],
}))

If issues persist:

typescript

// Explicitly guard
export default defineConfig(({ mode }) => ({
  plugins: [
    react(),
    mode === 'development' && reactDevToolsPlus(),
  ].filter(Boolean),
}))

问题：DevTools代码出现在生产包中。

解决方案: 插件默认会自动从生产构建中排除。验证配置：

typescript

// vite.config.ts
export default defineConfig(({ mode }) => ({
  plugins: [
    react(),
    // 插件默认仅在开发环境启用
    reactDevToolsPlus(),
  ],
}))

若问题仍存在：

typescript

// 显式添加环境判断
export default defineConfig(({ mode }) => ({
  plugins: [
    react(),
    mode === 'development' && reactDevToolsPlus(),
  ].filter(Boolean),
}))

Custom Base Path Not Working

自定义基础路径无效

Issue: DevTools not accessible at custom path.

Solutions:

typescript

// Ensure base includes leading and trailing slashes
reactDevToolsPlus({
  base: '/__custom_path__', // Correct
  // NOT: base: 'custom_path' or base: '/custom_path'
})

Then navigate to:

http://localhost:5173/__custom_path__/

问题：无法通过自定义路径访问DevTools。

解决方案:

typescript

// 确保基础路径包含首尾斜杠
reactDevToolsPlus({
  base: '/__custom_path__', // 正确写法
  // 错误写法：base: 'custom_path' 或 base: '/custom_path'
})

然后访问：

http://localhost:5173/__custom_path__/

Project Structure

项目结构

React DevTools Plus is a monorepo with the following key packages:

```
react-devtools
```
- Main Vite/Webpack plugin
```
react-devtools-client
```
- DevTools UI client
```
react-devtools-core
```
- Core functionality and plugin system
```
react-devtools-kit
```
- State management and messaging
```
react-devtools-overlay
```
- Floating overlay component
```
react-devtools-scan
```
- Render scanning utilities

React DevTools Plus是一个单体仓库，包含以下核心包：

```
react-devtools
```
- 主Vite/Webpack插件
```
react-devtools-client
```
- DevTools UI客户端
```
react-devtools-core
```
- 核心功能与插件系统
```
react-devtools-kit
```
- 状态管理与消息传递
```
react-devtools-overlay
```
- 悬浮浮层组件
```
react-devtools-scan
```
- 渲染扫描工具

Development

开发

If you need to contribute or debug the plugin itself:

bash

undefined

若需贡献代码或调试插件本身：

bash

undefined

Clone the repository

克隆仓库

git clone https://github.com/wzc520pyfm/react-devtools-plus.git cd react-devtools-plus

Install dependencies

安装依赖

pnpm install

Start development mode

启动开发模式

pnpm dev

Run Vite playground

运行Vite示例项目

pnpm play

Run Webpack playground

运行Webpack示例项目

pnpm play:webpack

Build all packages

构建所有包

pnpm build

Run tests

运行测试

pnpm test

Lint code

代码检查

pnpm lint

undefined

pnpm lint

undefined

Resources

资源

Documentation: https://react-devtools-plus.netlify.app/
GitHub: https://github.com/wzc520pyfm/react-devtools-plus
Issues: https://github.com/wzc520pyfm/react-devtools-plus/issues
License: MIT

文档：https://react-devtools-plus.netlify.app/
GitHub：https://github.com/wzc520pyfm/react-devtools-plus
问题反馈：https://github.com/wzc520pyfm/react-devtools-plus/issues
许可证：MIT