{T}

模板项目回切组件库包：pnpm link 联调、入口替换与 auto-import 缺失排查

概述

组件库做完之后最有价值的验证，不是继续在 Playground 里加页面，而是让原模板项目真正“吃回”这个包。这一节把原先的 admin/template 项目从“本地源码直连”切回“真正消费组件库包”的模式：删除被组件库吸收的部分代码、用本地 link 的包替代、批量修正页面 import、并排查因宿主环境变化导致的新问题。组件库真正成熟的标志，是原业务模板切回组件库包后还能正常工作。

学习目标

  • 用 pnpm link 把组件库包接回模板项目，模拟真实 npm 安装体验
  • 按真实依赖图删除已被组件库吸收的代码，而不是按目录名一刀切
  • 把页面里的组件、hooks、types 从本地路径切到包入口统一导入
  • 用 app.use(ElAdminComponents) 替代本地组件体系，让模板项目成为消费方
  • 排查切回后原模板依赖的 auto-import / auto-components 隐式能力消失问题

一、组件库成熟的标志是原模板项目真正“吃回”包

Playground 更像一个“最小消费环境”，原 admin/template 项目才是真正复杂的宿主环境：页面多、依赖多、组件使用方式更丰富，有真实布局、国际化、菜单、图表、音视频等场景。让原模板回头用上组件库包，一旦成功就说明组件库开始具备“反哺原项目”的能力。这一步本质上是做“业务回归测试”，比再造一个新 demo 更有价值。

text
组件库验证的层次
  1. Playground 最小验证
  2. 原模板项目回切验证

对当前这套项目，pnpm link 的成功率比 npm link 更高：原项目本来就用 pnpm 管依赖，沿用同一套包管理器去做 link，更少出现缓存、锁文件和 store 目录上的歧义。流程是先让组件库做全局 link，再在模板项目把全局 link 的包接进来。

bash
# 组件库项目
pnpm link --global

# 模板项目
pnpm link --global el-admin-components

课程里把组件库版本改成 1.0.0，本质是在帮助确认宿主拿到的是最新包。link 成功不代表类型、缓存和构建产物一定同步刷新，仍需重新验证。

三、按依赖图删除已被组件库吸收的代码

迁移删除不是“删掉所有旧代码”，而是分层判断：components 可删、directives 可删、modules 只删 i18n 相关部分、utils 不能立刻删（模板其他页面还在用）。工程迁移是“按依赖图删”，不是“按目录名删”。

text
迁移删除策略
  组件库已覆盖 -> 可删
  宿主仍直接使用 -> 先保留

utils 这类目录尤其容易误删，因为它既可能服务于组件库，也可能仍服务于宿主页面。

四、页面 import 语义从本地目录切到包入口

把页面、布局、功能模块里原本从本地路径 import 的组件、hooks、types，改成从 el-admin-components 入口导入。这一步不是机械替换路径，而是在验证组件库入口到底有没有把这些东西都设计成公共 API。替换后若仍报错，要么组件库没导出、要么宿主拿到的不是最新包、要么入口结构还不完整。

ts
import { VForm, useForm } from 'el-admin-components'
import type { FormSchema } from 'el-admin-components'

五、用 app.use(ElAdminComponents) 替代本地组件体系

组件库支持默认插件导出后，宿主最自然的接法就是 app.use(ElAdminComponents)，原先本地手工注册的组件体系退出舞台，模板项目开始真正以“消费方”身份使用组件库。如果默认导出里还顺带接入了 i18nPlugin 等公共能力，宿主侧代码会进一步收敛。

ts
import ElAdminComponents from 'el-admin-components'

app.use(ElAdminComponents)

六、切回后 auto-import / auto-components 隐式能力消失

切到外部组件库包后，最容易暴露的新问题不是业务逻辑，而是原模板依赖 unplugin-vue-components / auto-import 的隐式组件解析能力消失了：页面白屏、控制台没有明显大错误，但 Header、Menu 等组件根本没被导入。这是因为删掉本地组件目录后，原来自动解析本地 components 的链路断了。这类问题非常隐蔽，是下一节继续讲 components / imports 自动化接入的铺垫。

七、用复杂页面回归验证边界

不要停留在“首页能跑”，要继续检查布局页、表单页、echarts、音频、视频、编辑器这些高复杂度页面。简单页面通过不代表组件库替换成功，越依赖重组件、重交互的页面，越能验证边界是否真的理顺。组件库工程从来不是一次性设计完成的，宿主项目回切是最有价值的边界校验手段之一。

八、组件库边界由回切暴露的真实依赖关系决定

你以为某些能力已经进了组件库，结果宿主项目一切换就发现某些页面还直连本地文件，或某些工具方法根本还没被抽走。这种落差很真实，也很有价值。

组件库边界的最终形状，不是你在脑子里预想出来的，而是要经过三步走出来：

  • Playground 验证，确认运行期能力可用
  • 原模板回切，确认业务宿主能消费
  • 全量页面回归，确认复杂场景不漏

宿主项目回切是最有价值的边界校验手段之一。

它用真实页面把组件库边界“压出来”，把你原先对边界的假设逐一用真实依赖关系重新校验一遍。

更关键的是，回切过程中暴露的每一个报错，都在帮你修正“哪些能力真的进了组件库、哪些只是还挂在本地”的判断。

等复杂页面全部回归通过，组件库的公共边界才算被真实验证过，而不是停留在设计文档里。

组件库替换宿主项目成功的关键，不在于“少改几行”。

而在于你愿不愿意系统地把布局页、表单页、图表页、音视频页这些高复杂度页面全部重新走一遍。

简单页面通过不代表替换成功。越依赖重组件、重交互的页面，越能验证边界是否真的理顺。这一步本质上是在做一轮很像真实项目的回归测试，也是组件库走向成熟平台的必经之路。

常见问题

问题原因解决方案
组件库已 build 成功，但模板项目切回后大量报错原模板依赖本地源码和本地工具链，切换到包消费后边界改变逐层删除本地目录、逐页替换 import，重新验证公共 API 是否完整
pnpm link 后模板项目没拿到最新包宿主缓存了旧链接或旧版本信息确认组件库版本号、重新 link，检查 node_modules 实际指向
页面白屏但控制台提示不明显原模板依赖的 auto-import / auto-components 能力不再对外部包生效先显式导入页面所需组件，后续再评估给宿主重新接自动导入
utils 被删掉后模板项目报错这些工具仍被宿主页面直接使用保留仍在被宿主消费的内部工具，不要误删
组件能导入，但 hooks / types 仍报错入口增强后宿主页面还有旧路径未切到统一包入口全局搜索本地导入路径并逐步替换为包入口

延伸阅读