code-inspect-plugin-vue

Vite + Vue 3 插件：为模板中原生 HTML 与 Element Plus 风格组件（<el-*> / <ElXxx>）自动注入静态属性 data-insp-path，值格式为 项目根相对路径:行号，示例：src/views/home/index.vue:12，可直接从页面 DOM 溯源到源码位置。

安装

npm i code-inspect-plugin-vue -D

使用说明（Vite）

必须同时配置两项：

1. codeInspectorPluginVue()：Vite 前置插件，解析 .vue 文件、计算模板行号偏移
2. mergeVueInspectorCompilerOptions()：合并到 @vitejs/plugin-vue 配置，注入模板编译转换逻辑

基础完整配置

import { defineConfig } from 'vite';
import codeInspectorPluginVue, {
	mergeVueInspectorCompilerOptions,
} from 'code-inspect-plugin-vue';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
	plugins: [
		codeInspectorPluginVue(),
		vue(mergeVueInspectorCompilerOptions()),
	],
});

建议将本插件导入写在 @vitejs/plugin-vue 前面，保证编译顺序正常。

与现有 Vue 配置合并

原有 vue 配置直接作为第一个参数传入，自定义 nodeTransforms 会追加不覆盖：

vue(
	mergeVueInspectorCompilerOptions({
		script: {
			/* 原有script配置 */
		},
		template: {
			compilerOptions: {
				/* 你的原有 nodeTransforms 等配置 */
			},
		},
	}),
);

已自定义 template.compiler

如果你项目已经手动配置了 template.compiler，插件会自动包装你现有的 compile / parse 方法，不冲突且保留溯源能力。

效果示例

模板源码：

<el-card class="analysis-card">

页面渲染后 DOM 自动生成：

data-insp-path="src/views/course/analysis.vue:3"

• 路径基于 Vite config.root 相对路径，统一正斜杠
• 原生 HTML 与 Element Plus 风格标签（el-*、El+大写开头 Pascal）会注入；其它业务组件、<template>、slot 占位不注入，避免 TransitionGroup / RouterView 等片段根上的 Extraneous non-props attributes 告警。可用 injectElementPlus: false 关闭对 EP 的注入。

行为与限制说明

| 主题 | 说明 | | ---------------------------- | --------------------------------------------------------------------------------- | | 默认跳过规则 | 默认忽略 node_modules 下的 .vue 文件，可通过 exclude 自定义 | | 外部模板 <template src=""> | 使用外部模板文件时，无内联模板内容，不会注入 data-insp-path | | SSR 场景 | 插件会覆盖默认 @vue/compiler-ssr，适合普通 SPA 开发；SSR 项目如编译异常建议关闭 | | 语法解析错误 | 解析失败的文件直接跳过行号映射，不注入属性，不影响项目运行 |

API

codeInspectorPluginVue(options?)

Vite 插件，内置 enforce: 'pre'

• state：可选，共享运行时状态，默认内部单例
• attributeName：自定义 DOM 属性名，默认 data-insp-path
• exclude：(id) => boolean，返回 true 则跳过该文件处理
• injectElementPlus：是否在 Element Plus 风格组件上注入，默认 true（仅影响模板编译，本 Vite 插件自身不读取该项；请与 mergeVueInspectorCompilerOptions 第二参保持一致）
• elementPlusSkipTags：额外跳过注入的 EP 标签名数组（el-foo 或 ElFoo）；内置已跳过 el-config-provider（ElConfigProvider 为片段根，无法继承 fallthrough）

mergeVueInspectorCompilerOptions(vuePluginOptions?, insp?)

• 第一个参数：你原本传给 vue() 的配置对象
• 第二个参数：同上面 state / attributeName / exclude / injectElementPlus / elementPlusSkipTags 配置

默认导出

默认导出等价于 codeInspectorPluginVue

import codeInspector from 'code-inspect-plugin-vue';

许可证

MIT