某后台管理系统的约 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 的历史记录——这是花了大量时间走弯路的核心原因。
最初怀疑是 Dialog 组件的 v-model 响应式绑定写法有问题，依次尝试了：
v-bind="$attrs" 透传defineModel 宏<component :is> 渲染全部失败，症状完全不变。当时做出的判断是"根因未知，Dialog 组件本身有缺陷，无法修复"。
就在准备接受"放弃 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.0globs 换成官方标准的 dirs: ['src/components'] + globsExclude部署验证时，Dialog 仍然保留在排除名单里（通过手动注册保护），所以"通过了"的验证只能说明"新配置没有破坏原有 workaround"，并不能说明根因被修复了。
这一步犯了典型的因果混淆错误。
为了确认根因是否真的被修复，专门设计了一个对照实验：把 Pagination 也从排除名单中移除，恢复为标准的自动导入方式，用已升级的插件版本 + 标准 dirs 配置重新构建部署。
结果分页组件依然渲染失败，退化成了空标签。
这说明：插件版本升级和配置修正并不能解决这个问题。问题出在 unplugin-vue-components 处理"包装 Element Plus 组件的自定义组件"这类场景本身的深层缺陷，和版本号无关。
把 Pagination 的手动注册加回来，问题消失。至此确认：Dialog 和 Pagination 这两个包装 Element Plus 内部组件的自定义组件，都必须长期保留手动全局注册。这不是过渡方案，而是当前工具链下唯一可靠的解法。
恢复为简洁的 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"的方案，全屏切换、自定义标题栏等功能完整保留，代码风格保持一致。
编写了专门的回归测试用例（dialog-regression.spec.ts），覆盖用户管理（修改/分配角色）、角色管理、部门管理、岗位管理等 6 个核心用例，全部通过。
额外编写了独立的截图验证脚本，直接查看截图图片内容，确认弹窗标题、表单字段、自定义标题栏（全屏切换图标 + 关闭图标）均正常渲染——用视觉证据而非仅依赖断言通过与否。
这个环节发现了一个隐藏 bug：截图的文件名生成逻辑把中文用例名的非 ASCII 字符替换成下划线，导致多个不同用例的截图因为下划线数量相同而互相覆盖。磁盘上留下的截图其实是最后一个执行的用例，并不代表被断言"通过"的用例真的截图正确。这个问题被一并修复，保证每个用例的截图文件唯一。
8 种方案失败就断定"组件有问题、无法修复"是个典型的思维陷阱。真正原因其实在构建配置层，和组件代码本身无关。当反复在一个层面失败时，需要跳出当前文件的边界，去问："其他组件有没有类似症状？"——本例中的 Pagination 注释就是破局的关键线索。
特别是涉及截图证据时，要警惕文件名冲突等隐性问题。纯 DOM 断言只能验证"JS 没有报错、DOM 结构存在"，无法验证"弹窗真的渲染出来了且视觉正确"。截图留证时，文件名必须保证每个用例唯一。
升级依赖 + 修正配置后，验证环境通过，很容易得出"问题已解决"的结论。但此时 Dialog 仍然受手动注册保护，验证通过只能说明"workaround 没有被破坏"，不能证明根因被修复。专门设计一个对照实验（撤销 workaround、看问题是否复现） 才能得到可靠的结论。
app.component() 手动全局注册不是偷懒，而是绕开 unplugin-vue-components 在特定场景下（包装 Element Plus 内部组件）已知缺陷的必要手段。应该在代码注释中完整记录验证过程。后续新增的、内部包装了 Element Plus 组件的自定义组件（如新的表格、上传、树选择等封装），如果出现"外层挂载了但内部子组件不渲染"且无报错的症状，应优先怀疑这个已知缺陷，直接采用手动全局注册方案，不必重复排查过程。
排查过程中曾发生多次意外的文件覆盖——不同 AI 工具或协作者在几乎同一时刻修改相同的文件，导致部署时构建出错误版本。教训是：大范围改动要尽快提交，避免长时间停留在未提交的工作区；发现工作区状态与预期不符时，第一反应应该是查看 git diff/git log 对比预期，而不是假设自己的操作出了问题。
| 层面 | 错误归因 | 实际根因 |
|---|---|---|
| Dialog 组件 | v-model 绑定有缺陷 | 组件代码正常，无需修改 |
| 构建工具 | 版本太旧 + 配置拼写错误 | 插件本身的深层缺陷，升级无法解决 |
| 修复策略 | 需要全站替换为 ElDialog | 手动全局注册即可保留原组件 |
最终，196 个页面统一使用 Dialog 包装组件，全屏切换、自定义标题栏等功能完整保留，生产构建下弹窗 100% 正常。最关键的收获不是"问题被解决了"，而是如何避免在错误的方向上投入大量时间——多问一句"别的组件有没有同样的问题"，远比反复修改同一段代码有效。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。