Vue组件在.vue文件中报undefined或类型不识别，根本原因是Volar、unplugin-vue-components与类型声明三者未对齐：插件生成了注册逻辑，但Volar未通过components.d.ts获取类型信息，且TS Server未重载或experimental.enableAutoImport未开启。
Vue组件在.vue文件中直接使用却报undefined或类型不识别，不是插件没装，而是Volar + unplugin-vue-components + 类型声明三者没对齐。
为什么<ElButton>写了但TS报错、运行时报“is not defined”
常见错误现象：模板里写了<ElButton>，保存后没报错，但F12跳转失败、hover看不到类型、控制台提示ElButton is not defined。
根本原因不是插件没启用，而是三个环节断开了：
-
unplugin-vue-components生成了组件注册逻辑，但没让Volar“看见”这些组件的类型信息 - Volar默认只识别
script setup中显式defineComponent或import的组件，对自动导入的组件需额外提供.d.ts声明文件 - VSCode 的 TypeScript 服务未重新加载该声明文件（尤其改完
vite.config.ts后没重启 TS Server）
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 确保
Components({ dts: 'src/components.d.ts' })配置了dts路径，且该路径在tsconfig.json的"include"中（例如"include": ["src/**/*", "src/components.d.ts"]） - 改完配置后，在 VSCode 中按
Cmd+Shift+P→ 输入Restart TS server并执行 - 检查生成的
src/components.d.ts是否包含类似declare module 'vue' { interface GlobalComponents { ElButton: typeof import('element-plus')['ElButton'] } }的内容
unplugin-vue-components不生效？先查这三处硬性条件
插件静默失效最常卡在这几个地方，和代码逻辑无关，纯配置漏项：
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
-
vite.config.ts里plugins数组是否真包含了Components(...)调用（不是注释掉、不是拼错变量名、不是放在if (process.env.NODE_ENV === 'production')里） -
dirs配置是否覆盖实际组件路径——比如组件在src/@/components，但dirs写的是['src/components']，就会完全扫描不到 - 自定义组件文件名是否符合默认规则：默认只处理
PascalCase命名的.vue文件（如MyTable.vue），my-table.vue或index.vue需显式配extensions: ['vue']和deep: true
注意：resolvers（如ElementPlusResolver()）只影响第三方库组件，不影响你自己的src/components目录——那是dirs管的。
Volar必须开启experimental.enableAutoImport
即使unplugin-vue-components已正确注入组件，Volar 默认仍不会在template中触发自动导入建议。必须手动打开开关：
- 打开 VSCode 设置（
Cmd+,），搜索volar experimental - 勾选
Enable Auto Import（对应配置项为volar.experimental.enableAutoImport） - 该选项控制的是“在
template中输入<MyCom时是否弹出补全建议并自动插入import”，和unplugin-vue-components的运行时注册是两件事
不开启这个，你就只能靠手敲组件名，然后按Cmd+.手动触发导入——而Cmd+.本身又依赖前面说的.d.ts声明是否加载成功。
别忽略deep和directoryAsNamespace对嵌套组件的影响
当你的组件目录是src/components/form/Input.vue、src/components/form/Select.vue时，这两个配置决定你模板里怎么写：
-
deep: true（默认false）：开启后才会递归扫描子目录，否则只扫dirs直层 -
directoryAsNamespace: true（默认false）：开启后，Input.vue会被注册为FormInput，而不是Input；若设false，则直接叫Input，但同名冲突风险上升
典型踩坑：组件放src/components/ui/下，但deep: false，结果一个都扫不到；或者directoryAsNamespace: true后，在模板里还写<Input>，实际要写<UiInput>。
这类问题不会报错，只会“默默不注册”，排查时容易绕远路。
