Vite Plugin Devv Tagger

为 React 组件自动添加调试标记的 Vite 插件。

功能特性

• 🏷️ 自动为 JSX 元素添加调试标记属性
• 🎯 精确定位组件源码位置（文件路径、行号、列号）
• 🚀 零配置开箱即用
• 🎨 支持 TypeScript 和 JSX
• 🔧 可配置的标记选项
• 🏗️ 生产环境自动禁用
• 📊 构建统计信息输出
• 🎭 智能排除 Fragment 和 Three.js 组件

安装

npm install vite-plugin-devv-tagger --save-dev
# 或
yarn add vite-plugin-devv-tagger -D
# 或
pnpm add vite-plugin-devv-tagger -D

使用方法

基础用法

在 vite.config.ts 中配置：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import componentTagger from 'vite-plugin-devv-tagger';

export default defineConfig({
  plugins: [
    componentTagger(),  // 添加在 react 插件之前
    react(),
  ],
});

高级配置

import componentTagger from 'vite-plugin-devv-tagger';

export default defineConfig({
  plugins: [
    componentTagger({
      // 是否启用插件
      enabled: true,
      
      // 是否在生产环境中启用
      enableInProduction: false,
      
      // 要排除的文件路径模式
      exclude: ['node_modules', 'tests'],
      
      // 要处理的文件扩展名
      extensions: ['.jsx', '.tsx'],
      
      // 数据属性前缀
      prefix: 'data-devv',
      
      // 是否添加传统属性（兼容旧版本）
      includeLegacyAttributes: true,
    }),
    react(),
  ],
});

效果示例

输入代码

function App() {
  return (
    <div className="container">
      <h1>Hello World</h1>
      <button onClick={handleClick}>
        Click me
      </button>
    </div>
  );
}

输出代码（开发环境）

function App() {
  return (
    <div data-devv-id="src/App.tsx:3:4" data-devv-name="div" className="container">
      <h1 data-devv-id="src/App.tsx:4:6" data-devv-name="h1">Hello World</h1>
      <button data-devv-id="src/App.tsx:5:6" data-devv-name="button" onClick={handleClick}>
        Click me
      </button>
    </div>
  );
}

环境变量控制

通过环境变量控制插件行为：

# 开发环境（添加标记）
npm run dev

# 生产构建（不添加标记）
IS_PROD=true npm run build

# 开发环境也不添加标记
IS_PROD=true npm run dev

配置选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | enabled | boolean | true | 是否启用插件 | | enableInProduction | boolean | false | 是否在生产环境中启用 | | exclude | string[] | ['node_modules'] | 要排除的文件路径模式 | | extensions | string[] | ['.jsx', '.tsx'] | 要处理的文件扩展名 | | prefix | string | 'data-devv' | 数据属性前缀 | | includeLegacyAttributes | boolean | true | 是否添加传统属性 |

排除的元素

插件会自动排除以下元素：

• React Fragment
• Three.js/React Three Fiber 组件
• @react-three/drei 导入的组件

构建统计

构建完成后会输出统计信息：

[devv-tagger] 构建统计:
  - 总文件数: 45
  - 处理文件数: 32
  - 标记元素数: 256

开发提示

1. 插件在 enforce: "pre" 模式下运行，确保在其他插件之前处理代码
2. 使用 AST 解析确保准确识别 JSX 结构
3. 自动生成 Source Map 支持调试
4. 标记信息包含文件路径、行号、列号，方便精确定位

License

MIT