宿主项目自动导入回接：VP 组件 custom resolver、hooks auto-import 与缓存排查

概述

宿主项目切换到组件库包之后，如果不重新配置自动导入链路，页面虽能跑，开发体验会明显退化。这一节把宿主项目的开发体验恢复到接近原模板的状态：给 unplugin-vue-components 增加自定义 resolver，让 VP* 组件自动从组件库包解析；给 unplugin-auto-import 增加自定义 imports，让 useForm、useMenu 这类 hooks 自动解析。组件库抽离完成后，宿主的“自动导入体验”不是天然保留的，它必须通过新规则重新接回。

学习目标

• 理解切回组件库包后自动导入链路必须重新接回，否则体验退化
• 用 unplugin-vue-components 的 custom resolver 解析 VP* 组件
• 理解 resolver 只处理模板标签，旧 import 和旧组件名仍需替换
• 切换来源后删除旧 components.d.ts 并重建声明文件
• 用 unplugin-auto-import 显式 imports 接回组件库 hooks
• 排查 auto-import 接通后暴露的组件库源码质量问题（如 useRoute 漏导入）
• 处理 .vite 缓存、声明文件、包内容三者不同步

一、切回组件库包后自动导入体验会退化

切到组件库包后，以前模板里自动出现的组件不见了，useForm、useMenu 这类 hooks 也不再自动出现。组件库替换宿主项目，不只是“路径替换”，开发体验也得重新恢复，否则每个页面都要手动 import 组件、import hooks、修类型提示，和原模板使用习惯差距太大。这一节是在补“工程体验闭环”。

切到组件库包后
  -> 运行时链路要通
  -> 自动导入链路也要重新接回

二、custom resolver 与统一前缀一起使用

既然组件库已统一成 VPForm、VPMenu、VPHeader，宿主就可通过组件名前缀识别这些组件。unplugin-vue-components 官方 README 明确支持自定义 resolver，思路是：若组件名满足条件，返回 { name, from }，插件就自动从对应包导入。这正是统一前缀策略的实际落地价值。

Components({
  resolvers: [
    (componentName) => {
      if (componentName.startsWith('VP')) {
        return {
          name: componentName,
          from: 'el-admin-components',
        }
      }
    },
  ],
})

三、resolver 只处理模板标签，旧 import 仍需替换

配置完 resolver 后不是一切自动变好，还要继续做两件事：把原来的 Menu、Header 标签改成 VPMenu、VPHeader，把页面顶部残留的本地 import 删掉。resolver 能处理的是模板中的组件标签，它不能替你批量重命名页面标签、自动清理旧 import 语句、修复旧逻辑里的其他路径依赖。

<template>
  <VPMenu />
  <VPHeader />
</template>

四、规则切换后删除旧 components.d.ts 重建

组件已切到从 el-admin-components 导入，但宿主旧 components.d.ts 还在，里面仍引用原本地 src/components 内容，会出现“页面改对了、类型提示却还引用旧组件”的混乱。直接删掉旧的 components.d.ts、重启 dev server，让它重新生成，是非常正确的做法。自动生成的 d.ts 不是永远可信，取决于当前配置和缓存状态。

规则切换后
  -> 删除旧 components.d.ts
  -> 重启 dev server
  -> 让插件重新生成声明文件

五、unplugin-auto-import 用显式 imports 接回 hooks

unplugin-auto-import 官方 README 支持在 imports 用对象形式声明某个包里有哪些函数需要自动导入。useForm、useMenu、useAudioPlayer 就非常适合直接写进自定义 imports 配置。hooks 比组件更适合走 imports 显式映射，先用最直观的对象形式而非更复杂的 package preset。

AutoImport({
  imports: [
    'vue',
    {
      'el-admin-components': [
        'useForm',
        'useMenu',
        'useAudioPlayer',
      ],
    },
  ],
})

六、auto-import 接通后暴露的是组件库源码质量问题

auto-import 和 resolver 都配上了，页面仍报错，最后发现根因是组件库里的 useMenu 本身少了 useRoute 导入。自动导入配置只是把代码接进来，不会替你修组件库源码自身的逻辑漏洞。宿主真正开始通过公共 API 使用 composables 时，组件库内部遗漏的依赖就会被放大暴露。真正修复动作应回到组件库改源码、重建，再回宿主验证。

import { useRoute } from 'vue-router'

七、删缓存 + 重构建 + 重启 dev 是必要的同步手段

改了组件库源码、宿主也重新 link 了，页面还是报旧错误，根因是三层东西可能不同步：组件库 dist、宿主 node_modules / link 结果、Vite 的 .vite 缓存和自动生成的 d.ts。通过删除 .vite、重新 build、重新启动 dev server 来强制系统回到一致状态，这是多层缓存系统的现实要求，不是玄学重启。

改包源码
  -> 重新 build
  -> 更新宿主依赖
  -> 删除 .vite 缓存
  -> 重启 dev

常见问题

延伸阅读

• 上一篇：组件库别名导出自动化
• 下一篇：组件库 Vite 插件配置导出
• 相关：unplugin-vue-components
• 相关：unplugin-auto-import