Vue 3 + Vite 生产构建下自定义弹窗组件大面积失效：根因排查与修复实录
Vue 3 + Vite 生产构建下自定义弹窗组件大面积失效：根因排查与修复实录
一、问题现象
某后台管理系统的约 196 个页面使用的 Dialog 包装组件（对 Element Plus ElDialog 的二次封装，提供全屏切换、自定义标题栏等能力）在生产构建后大面积失效：点击"修改、编辑、详情、分配角色"等按钮后模态框不弹出，且控制台没有任何报错。
此前已经有同事排查过一轮，尝试了 8 种修复 Dialog 组件内部 v-model 绑定方式的方案，全部失败，最终结论是"根因未确认，唯一可行方案是把全部 196 个文件的 <Dialog> 替换成 <ElDialog>"。但这意味着放弃一个封装良好的组件，以及它提供的全屏切换、自定义标题栏等功能。
本文记录的是在此基础之上继续深挖，最终找到真正根因并彻底修复的过程。
二、真正的根因
Dialog 组件本身的 v-model 绑定逻辑（defineModel + ElDialog 直接绑定）没有问题。问题出在构建配置。
项目使用 unplugin-vue-components 插件（版本 0.25.2）进行组件的自动按需导入。配置中使用了非标准的手写 globs 模式扫描组件目录：
globs: ["src/components/**/**.{vue, md}", '!src/components/DiyEditor/components/mobile/**', '!src/components/Pagination/**']
这里有两个明显的问题：
**/**是重复的双通配符，虽然不会报错，但也不是标准写法{vue, md}花括号展开里逗号后多了一个空格，变成了" md"，实际变成了两个模式：*.vue和*. md（注意空格），后者永远匹配不到任何文件
与此同时，老版本 unplugin-vue-components（0.25.2）搭配 Vite 6，在生产构建的模块解析过程中，对"内部包装了 Element Plus 组件的自定义组件"解析不稳定。具体表现为：外层组件正常挂载（DOM 中能看到内部表单字段），但被包装的 ElDialog 压根不渲染——且没有任何报错。
关键线索：项目里另一个组件 Pagination（列表分页组件，同样是包装 ElPagination）早就踩过完全相同的坑。当时的解决方案也是把它从自动扫描中排除、改成手动 app.component() 全局注册，并且代码注释里明确记录了原因。这两个组件的故障症状、修复方式高度一致，属于同一类问题。
但此前排查 Dialog 时，所有人都盯着 Dialog 组件本身的代码反复修改，没有人去翻 Pagination 的历史记录——这是花了大量时间走弯路的核心原因。
三、排查过程（弯路与转折）
第一轮：8 种方案全部失败
最初怀疑是 Dialog 组件的 v-model 响应式绑定写法有问题，依次尝试了：
v-bind="$attrs"透传- computed + modelValue/update:modelValue 桥接
defineModel宏- ref + watch 手动同步
- 动态
<component :is>渲染 - 显式 modelValue prop + emits
- 去掉二次封装、直接内联 ElDialog
- 包装一层中间组件
全部失败，症状完全不变。当时做出的判断是"根因未知，Dialog 组件本身有缺陷，无法修复"。
转折点：注意到 Pagination 的注释
就在准备接受"放弃 Dialog 组件、全站替换 ElDialog"的方案时，注意到 src/components/index.ts 中有一段注释——Pagination 组件早就因为完全相同的症状被处理过，处理方式是手动全局注册。
此时产生了一个新的假设：问题出在 unplugin-vue-components 的自动导入机制在生产构建下的缺陷，而非 Dialog 组件的代码本身。
第二轮验证假设
验证方案很简单：把 Dialog 从自动扫描的 globs 中排除，在 src/components/index.ts 中手动 import 并 app.component('Dialog', Dialog) 全局注册。然后把一个测试页面从 <ElDialog> 恢复回 <Dialog>，构建部署到生产环境。
弹窗恢复正常。 假设成立。
第三轮：尝试根治
进一步怀疑是"插件版本太老 + globs 手写配置有 bug"两个问题叠加导致，于是：
- 升级
unplugin-vue-components从0.25.2到30.0.0 - 把手写
globs换成官方标准的dirs: ['src/components']+globsExclude
部署验证时，Dialog 仍然保留在排除名单里（通过手动注册保护），所以"通过了"的验证只能说明"新配置没有破坏原有 workaround"，并不能说明根因被修复了。
这一步犯了典型的因果混淆错误。
第四轮：对照实验推翻假设
为了确认根因是否真的被修复，专门设计了一个对照实验：把 Pagination 也从排除名单中移除，恢复为标准的自动导入方式，用已升级的插件版本 + 标准 dirs 配置重新构建部署。
结果分页组件依然渲染失败，退化成了空标签。
这说明：插件版本升级和配置修正并不能解决这个问题。问题出在 unplugin-vue-components 处理"包装 Element Plus 组件的自定义组件"这类场景本身的深层缺陷，和版本号无关。
最终确认
把 Pagination 的手动注册加回来，问题消失。至此确认：Dialog 和 Pagination 这两个包装 Element Plus 内部组件的自定义组件，都必须长期保留手动全局注册。这不是过渡方案，而是当前工具链下唯一可靠的解法。
四、修复措施
Dialog 组件本身
恢复为简洁的 defineModel + ElDialog 直接绑定实现。组件逻辑没有任何问题，不需要改动。此前认为"组件本身有缺陷"的判断是错误的。
构建配置
- unplugin-vue-components 从 0.25.2 升级到 30.0.0
- Components() 配置改用标准 dirs: ['src/components'] + globsExclude
- 修正了原来手写 globs 的空格错误
组件注册策略
Dialog、Pagination 两个组件保留在 globsExclude 中，不走自动导入，改为在 src/components/index.ts 中 import 后手动 app.component() 全局注册，并附上完整的验证过程注释。
页面文件
全部 196 个页面保持/恢复为 <Dialog v-model="..."> 的统一写法。没有采用"替换成 ElDialog"的方案，全屏切换、自定义标题栏等功能完整保留，代码风格保持一致。
五、验证方式
E2E 自动化回归
编写了专门的回归测试用例（dialog-regression.spec.ts），覆盖用户管理（修改/分配角色）、角色管理、部门管理、岗位管理等 6 个核心用例，全部通过。
截图核验（重要教训）
额外编写了独立的截图验证脚本，直接查看截图图片内容，确认弹窗标题、表单字段、自定义标题栏（全屏切换图标 + 关闭图标）均正常渲染——用视觉证据而非仅依赖断言通过与否。
这个环节发现了一个隐藏 bug：截图的文件名生成逻辑把中文用例名的非 ASCII 字符替换成下划线，导致多个不同用例的截图因为下划线数量相同而互相覆盖。磁盘上留下的截图其实是最后一个执行的用例，并不代表被断言"通过"的用例真的截图正确。这个问题被一并修复，保证每个用例的截图文件唯一。
六、经验与反思
1. "无解"往往是假象
8 种方案失败就断定"组件有问题、无法修复"是个典型的思维陷阱。真正原因其实在构建配置层，和组件代码本身无关。当反复在一个层面失败时，需要跳出当前文件的边界，去问："其他组件有没有类似症状？"——本例中的 Pagination 注释就是破局的关键线索。
2. E2E 测试通过 ≠ 功能正常
特别是涉及截图证据时，要警惕文件名冲突等隐性问题。纯 DOM 断言只能验证"JS 没有报错、DOM 结构存在"，无法验证"弹窗真的渲染出来了且视觉正确"。截图留证时，文件名必须保证每个用例唯一。
3. "升级修复了问题"需要单独设计实验证明
升级依赖 + 修正配置后，验证环境通过，很容易得出"问题已解决"的结论。但此时 Dialog 仍然受手动注册保护，验证通过只能说明"workaround 没有被破坏"，不能证明根因被修复。专门设计一个对照实验（撤销 workaround、看问题是否复现） 才能得到可靠的结论。
4. 手动全局注册 vs 自动导入
app.component() 手动全局注册不是偷懒，而是绕开 unplugin-vue-components 在特定场景下（包装 Element Plus 内部组件）已知缺陷的必要手段。应该在代码注释中完整记录验证过程。后续新增的、内部包装了 Element Plus 组件的自定义组件（如新的表格、上传、树选择等封装），如果出现"外层挂载了但内部子组件不渲染"且无报错的症状，应优先怀疑这个已知缺陷，直接采用手动全局注册方案，不必重复排查过程。
5. 多工具协作时的工作区管理
排查过程中曾发生多次意外的文件覆盖——不同 AI 工具或协作者在几乎同一时刻修改相同的文件，导致部署时构建出错误版本。教训是：大范围改动要尽快提交，避免长时间停留在未提交的工作区；发现工作区状态与预期不符时，第一反应应该是查看 git diff/git log 对比预期，而不是假设自己的操作出了问题。
七、总结
| 层面 | 错误归因 | 实际根因 |
|---|---|---|
| Dialog 组件 | v-model 绑定有缺陷 | 组件代码正常，无需修改 |
| 构建工具 | 版本太旧 + 配置拼写错误 | 插件本身的深层缺陷，升级无法解决 |
| 修复策略 | 需要全站替换为 ElDialog | 手动全局注册即可保留原组件 |
最终，196 个页面统一使用 Dialog 包装组件，全屏切换、自定义标题栏等功能完整保留，生产构建下弹窗 100% 正常。最关键的收获不是"问题被解决了"，而是如何避免在错误的方向上投入大量时间——多问一句"别的组件有没有同样的问题"，远比反复修改同一段代码有效。
浙公网安备 33010602011771号