vite-plugin-vue-source-labels

vite-plugin-vue-source-labels

独立、仅开发环境启用的 Vue 3 / React / Vite 来源标注插件。Vue SFC 和 React JSX/TSX 中有可见 DOM 矩形的原生标签、可定位的组件根节点都有透明虚线框、左上角名称；点击名称默认复制相对项目根目录的源文件路径:行号，例如 src/App.vue:12。原生标签指向声明该节点的文件，组件指向引用（使用）该组件的位置——例如模板里写 <Child/> 的那一行。左上角「标注设置」打开紧凑配置面板，分别勾选组件名称和标签名称，也可开启「复制完整路径」以复制绝对源文件路径。分类和复制方式都在当前会话记忆。按 Escape 或点击面板外部关闭配置。

接入

npm install -D vite-plugin-vue-source-labels

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueSourceLabels from 'vite-plugin-vue-source-labels'

export default defineConfig({
  plugins: [vue(), vueSourceLabels()],
})

上面保留原有 Vue 默认入口。React 脚手架使用命名入口，无需安装 Vue：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react' // 也支持 @vitejs/plugin-react-swc
import { reactSourceLabels } from 'vite-plugin-vue-source-labels'

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

sourceLabels() 命名入口同时处理 .vue、.jsx 和 .tsx，适用于混合项目。也可以组合 Vue 默认入口与 reactSourceLabels()；每个框架只变换一次，运行时只注入一次，初始可见性以第一个入口的配置为准。源码插桩有明确钩子顺序，不要求调整框架插件在数组中的位置。

不需要预构建。Node ^20.19.0 || >=22.12.0；Vue 3.3+；React/React DOM 18 或 19；Vite 5–8。Vue 与 React 都是可选 peer，只安装使用方项目需要的框架。

尚未发布到 npm 时，可先克隆本仓库并在插件目录运行 npm install，再在使用方项目中执行 npm install -D /path/to/vite-plugin-vue-source-labels。Vite 配置中的包导入方式保持不变。

也可以使用打包产物接入：在本仓库运行 npm run build，然后在使用方项目执行 npm install -D /path/to/artifacts/npm/vite-plugin-vue-source-labels-0.1.2.tgz。

可选配置：

vueSourceLabels({
  enabled: true, // 首次会话默认开启；已有sessionStorage分类选择优先
  include: filename => !filename.includes('/generated/'), // 绝对源文件名
})

显示与来源

• <ComponentName> 代表组件；原生标签显示 div、span 等。原生标签来源是声明该节点的文件；组件来源是引用该组件的位置（模板/JSX 里使用该组件的那一行）。同一组件的多个实例、多个根分别指向各自的使用处，根组件没有引用方时回退到组件自身文件。Vue 由渲染 vnode 上的调用点元数据精确定位；React 在使用处注入调用点标记，只有组件把未知属性透传到 DOM 根节点时才生效，否则回退到组件自身声明。悬浮提示与复制内容统一包含行号。
• 固定 7 种颜色按「文件路径 + 名称」稳定散列、循环使用；重复加载和刷新颜色一致。
• 复制的相对路径以 Vite 配置的 root 为基准，使用 / 分隔；项目根目录以外的同盘文件保留 ../ 路径。Windows 跨盘或不同网络共享无法表示相对路径时使用完整路径。勾选「复制完整路径」后保留原始绝对路径；悬浮提示与实际复制内容一致，切换复制方式不改变标注显示。
• 同坐标的嵌套名称排列避让，保留各自复制入口。框和空白区域不拦截应用点击，只有名称按钮及配置面板响应点击。悬浮或键盘聚焦名称会高亮文字及关联边框，不添加逐帧监听或动画。
• 支持 v-if、v-for、动态组件、组件别名、slots、Fragment 多根、Teleport、KeepAlive 和 Vue HMR；原生标签及组件来源分别显示。
• 组件多个根节点分别显示组件名称，且都指向同一个引用位置。slot 中原生标签路径归属声明该 slot 内容的文件。
• 不修改 Vue 生命周期已有逻辑、inheritAttrs 或应用布局；组件注册沿用原对象身份并追加局部 mixin。
• React 支持函数、箭头、class、memo/forwardRef、Fragment、条件、数组和 map 中可静态定位的原生根；多个根分别保留组件标签。组件使用处会附加调用位置属性，组件把它透传到 DOM 根节点时标签即指向引用位置；不修改 Hooks、refs、组件身份和 Fast Refresh，不依赖 Fiber 或 DevTools 私有接口。

性能与边界

事件驱动，使用 MutationObserver、IntersectionObserver 和 ResizeObserver；只测量视口内目标，几何读取与 overlay 写入分开，多次组件更新合并为一次 requestAnimationFrame。无永久动画循环或定时轮询。两类全部隐藏后断开观察器、移除布局/复制监听、取消待执行帧并移除全部标签和边框；保留组件实例注册以便再次打开。

滚动、调整窗口、DOM 变化、大小变化、图片加载、动画/过渡结束时刷新。持续 CSS transform 动画进行中不逐帧跟随；动画结束后对齐。这是有意保留的性能取舍。

Vue 只支持 SFC 的 HTML 模板；React 支持标准 JSX/TSX，包括静态 JSX 常量和具名 map 回调。普通 HTML、外部 template src、Pug、Flow、v-html/第三方脚本创建的内部节点和 node_modules 内组件不处理。React 仅透传返回其它组件、跨文件生成、多个组件共用同一 JSX/回调或无法静态判定的根，不强行追加组件标签；其中本地 JSX 的原生标签仍可定位。无可见 DOM 矩形、display: contents 容器和注释/文本根节点没有可描绘边框。Vue/React 的 SSR 变换都跳过；仅浏览器开发页面显示 UI。

构建阶段通过 apply: 'serve' 完全排除插件，生产输出不包含源路径、标记属性或 overlay 运行时。开发页面暴露绝对文件路径是此调试工具的功能，请只在本地开发环境使用。

本包开发

npm install
npm test
PUPPETEER_EXECUTABLE_PATH="/path/to/chrome" npm run test:browser
PUPPETEER_EXECUTABLE_PATH="/path/to/chrome" npm run test:compat
npm pack --dry-run

test:compat 首次运行会安装 test/projects/ 中子项目依赖，各项目使用精确版本和锁文件。每次安装真实 npm pack 产物，验证浏览器路径/行号、生命周期、分类开关、停止观察、状态更新、HMR 和生产输出；可用 -- --project react-vite8 单独运行一行。

这些是固定回归版本，不是对 Vue/React 官方 LTS 的承诺。Vite 5 已结束维护，只保留旧项目兼容回归；新项目依照 Vite 维护策略选择版本。Vue 与其 SFC 编译器的版本关系遵循 Vue 发布说明，框架维护策略见 React 版本策略。

浏览器内可读取 document.querySelector('vue-source-labels').__vslStats 的只读诊断数据（分类选择、完整路径复制开关、跟踪目标、可见目标、标签数量、累计帧数和观察器状态）。

打包与发布

npm ci
npm run build

build 与 pack:release 都只生成本地产物，不执行发布。默认运行单测、类型检查，核对发布文件，并从真实归档安装到独立临时项目验证 Vue/React 入口、类型和虚拟运行时。产物输出到 artifacts/npm/：.tgz 为可发布安装包，release.json 记录版本、文件清单、验证结果和手动发布命令，SHA256SUMS.txt 用于核对归档完整性。验证失败不会替换已有产物，也不会清空输出目录。

完整浏览器版本矩阵可在打包时一起运行：

PUPPETEER_EXECUTABLE_PATH="/path/to/chrome" npm run build -- --full
npm run build -- --out-dir /path/to/output

源码使用 ESM，打包保留 src/ 模块目录，不生成单文件 bundle。files 白名单排除测试子项目、开发脚本、依赖、浏览器截图及本地记录。发布目标显式指定 npm 官方 registry；运行打包脚本不需要登录 npm。

稍后由你登录并发布已经验证的归档：

npm login --registry=https://registry.npmjs.org/
npm publish artifacts/npm/vite-plugin-vue-source-labels-0.1.2.tgz --access public --registry=https://registry.npmjs.org/

发布文件名以本次生成的清单为准。后续版本先更新 package.json 与锁文件，再重新打包；已发布的相同版本不能覆盖。命令与生命周期说明见 npm publish 和 npm scripts。