unplugin-vue-components比手写import更可靠，因其在构建时静态分析template，自动注册实际使用的组件并生成类型声明，避免手动import易漏、难同步、类型丢失等问题。
为什么unplugin-vue-components比手写import更可靠
因为 Vue 单文件组件里用到的组件（比如 ElButton、NaiveButton）不会自动注册，Vite 默认不扫描模板里的标签名去推导依赖。手动 import 容易漏、重构时难同步、类型提示也断掉。unplugin-vue-components 在构建时静态分析 <template>，只注册实际出现的组件，且自动生成类型声明。
实操建议：
- 装包：
npm add -D unplugin-vue-components（Vue 3 + Vite 项目） - 插件必须加在
vite.config.ts的plugins数组最前面，否则可能被其他插件（如unplugin-auto-import）干扰解析顺序 - 若用 TypeScript，需在
env.d.ts中补一句/// <reference types="unplugin-vue-components/svg.d.ts" />，否则图标组件类型报错 - 别把
dirs配成['src/components']后又在子目录放index.ts导出 —— 插件默认不递归解析入口文件，会漏注册
components.d.ts 不更新？检查这三个地方
常见现象：改了组件名、新增了 .vue 文件，但 components.d.ts 没变，开发时仍报 Unknown custom element。
原因和解法：
立即学习“前端免费学习笔记（深入）”；
- VS Code 缓存了旧的类型声明 —— 关闭再重开项目，或执行
npm run dev后等 2 秒再切编辑器标签 - Vite 开启了
cache: { dir: 'node_modules/.vite' }但没配rollupOptions.watch.exclude，导致插件的 watch 机制失效 —— 加上exclude: ['node_modules/**'] - 组件文件名含大写字母（如
MyCard.vue），但模板里写了<my-card>—— 插件默认按 PascalCase 匹配，得显式配resolvers: [ElementPlusResolver({ importStyle: 'sass' })]这类适配器，不能只靠文件名推导
按需加载样式时，importStyle 和真实路径对不上
比如用了 NaiveUI，配了 importStyle: 'css'，但运行时报 Cannot find module 'naive-ui/lib/button/style/css' —— 这不是插件 bug，是包的导出结构变了。
关键判断点：
- 进
node_modules/naive-ui/lib/button/看有没有style目录；没有就别设importStyle，改用全局样式或手动import 'naive-ui/lib/index.css' -
Element Plus的importStyle: 'sass'要求项目已装sass和sass-loader（Vite 本身不处理.scss引入链） - 如果组件库用的是
unplugin-vue-components不支持的私有导出方式（如某些内部 UI 库用export * from './xxx'套了三层），插件无法正确定位样式路径，只能退回到手动import
和 unplugin-auto-import 共存时，defineComponent 类型丢失
典型症状：组件里用 defineComponent({ setup() { ... } })，TS 提示 Cannot find name 'defineComponent'，但 ref、computed 又正常。
这是因为两个插件都生成 auto-imports.d.ts，但 unplugin-vue-components 默认不注入 Vue 的全局类型辅助，而 unplugin-auto-import 若没显式配 imports: ['vue']，就会漏掉 defineComponent。
解决办法只有这一种：
- 在
unplugin-auto-import的配置里加imports: ['vue', '@vue/runtime-core']，后者专门提供defineComponent类型 - 删掉
src/shims-vue.d.ts里重复的declare module '*.vue'声明，避免和插件生成的类型冲突 - 别指望
unplugin-vue-components自动修这个 —— 它只管组件，不管组合式 API 的类型注入
按需引入真正卡住人的，从来不是插件装不装得上，而是哪一层类型没对齐、哪个路径拼错了、或者哪个缓存没清干净。多看插件输出的 debug 日志（配 verbose: true），比反复重装 node_modules 有用得多。
