组件库批量打包排错：第三方依赖收敛

概述

当统一入口开始批量导出组件，组件库第一次暴露出「真实依赖图」：vditor、video.js、vue-echarts、@iconify/vue、vue-router、vue-i18n、@vueuse/core……很多问题在「只导出一个简单组件」时被隐藏，批量导出后全部浮出水面。这一节表面是在「一个报错接一个报错修」，本质上有四条更深的主线：把引用到的第三方依赖逐步收敛清楚、明确哪些应该 external 给使用方、处理 defineProps 复杂类型的编译限制、避免 i18n 和 import.meta.glob 把大量用不到的语言资源卷进产物。

学习目标

• 理解批量导出后第一次全量 build 是「组件库依赖边界审计」的机会
• 掌握 peerDependencies 的核心意义：明确要求消费方必须提供哪些运行环境
• 用 @vue-ignore 绕过 defineProps 复杂 extends 基类型的编译报错，并理解其代价
• 认识 import.meta.glob 大范围匹配会把整套语言资源卷入产物的风险
• 收敛 props 设计：与其全透传第三方类型，不如只暴露真正需要的字段

一、批量导出暴露真实依赖图

一旦把组件开始批量导出，问题马上出现：vditor、video.js、vue-echarts、@iconify/vue、vue-router、vue-i18n、@vueuse/core 等依赖全部进入视野。这说明组件库在「只导出一个简单组件」时很多问题被隐藏了；一旦批量导出，真实依赖图就暴露出来。这个阶段最难的判断不是「装不装」，而是：这个依赖是组件库运行时必须带上的、应该由消费方提供的，还是只是开发阶段需要的。

组件库越进入真实业务组件阶段，依赖边界越重要。「先装上再说」适合临时打通链路，但不适合最终发布。课程把一部分依赖上移到 peerDependencies，本质上就是在收敛边界。

二、peerDependencies 的核心意义

peerDependencies 的核心意义不是「减少安装」，而是「明确要求消费方必须提供哪些运行环境」。把 vue、@vueuse/core、vue-router、大体量的 echarts 等依赖往 peerDependencies 收敛，真实含义是：组件库不想把这些依赖完全打进包里，希望消费方项目已经具备这些运行环境，从而避免重复打包、版本冲突和包体积膨胀。

{
  "peerDependencies": {
    "vue": "^3.0.0",
    "echarts": "^5.0.0",
    "vue-echarts": "^6.0.0",
    "vue-router": "^4.0.0",
    "@vueuse/core": "^10.0.0"
  },
  "devDependencies": {
    "vue-router": "^4.0.0",
    "vue-i18n": "^9.0.0"
  }
}

注意：如果组件库开发期要引用这些包做本地构建和类型检查，它们通常仍需同时存在于 devDependencies。peerDependencies 不是「不装了」，而是「运行时由使用者承担」。大体量三方库很适合优先评估是否 external + peer；如果某个依赖只是极罕见组件才用到，要特别警惕它是否值得成为整个组件库的刚性运行时前置。

三、错误驱动收敛依赖

课程的推进顺序很真实：先尝试 build，看缺什么依赖，安装它，再次 build，沿报错链往下修。对大型组件迁移，这种「从错误驱动收敛依赖」的方式很常见，因为很多隐性依赖只有在真正打包时才会暴露。这种方式适合从 0 到 1 阶段，但不适合长期无脑堆依赖——每修一类问题都要顺手思考这个依赖最后应留在哪一层。最终目标不是「把错误消掉」，而是「把依赖边界整理清楚」。

四、defineProps 复杂类型与 @vue-ignore

课程里遇到的典型报错是 Failed to resolve extends base type。这类问题常出现在组件 props 直接扩展复杂第三方类型或多层级泛型 / utility type 时。这不代表 TypeScript 本身不支持，而是 Vue SFC 编译器在编译 defineProps<T>() 时需要把类型转成运行时可理解的信息，某些复杂场景目前仍解析不了。

import type { IconProps as IconPropsOrigin } from '@iconify/vue'

export interface IconProps extends /* @vue-ignore */ IconPropsOrigin {
  size?: string | number
}

/* @vue-ignore */ 的作用不是「修好类型」，而是告诉 Vue SFC 编译器：这段基础类型你先别继续展开解析。代价通常是这部分基类型的属性在运行时会更像 fallthrough attrs，需要自己承担类型可维护性的责任。它更像编译层 workaround 而非长期完美方案；如果组件是基础核心组件，长期更推荐把真正需要暴露的 props 手工重新定义出来。

五、props 设计应收缩暴露面

课程用 IconProps 场景说明：直接继承第三方复杂 props 类型，会给 defineProps 带来编译压力。从组件库设计角度，这本身也是一种信号——你真的需要把底层第三方组件的全部 props 暴露给使用者吗？很多时候并不需要。更稳定的做法是手工定义真正需要的字段，或只挑选少量必要字段。

interface IconProps {
  icon: string
  width?: string | number
  height?: string | number
  color?: string
}

「少暴露一点」在组件库里往往比「全透传」更可维护；暴露得越多，和第三方库的耦合越深。编译器报错很多时候只是表象，背后其实是接口设计过宽。

六、import.meta.glob 与 i18n 资源裁剪

import.meta.glob 很方便，但如果你直接对整片语言目录做匹配，Vite 会根据匹配模式生成导入映射，匹配到的模块都会进入构建分析范围。课程里组件库为了国际化原样搬来动态收集语言文件的逻辑，结果产物里出现大量语言相关模块。

更稳妥的做法是「显式导入少数必要语言」或「真正按需 lazy load」，而不是无差别全量收集。Vue I18n 官方提供了 lazy loading 语言包模式；Element Plus 官方推荐直接从 element-plus/es/locale/lang/zh-cn、en 等路径显式导入语言包。

import zhCn from 'element-plus/es/locale/lang/zh-cn'
import en from 'element-plus/es/locale/lang/en'

export const elementPlusLocales = {
  'zh-cn': zhCn,
  en,
}

组件库通常不应该替消费方做「支持全世界语言」的默认决定，应尽量只携带最小必要资源。课程从「全量收集」收敛到「显式导入两种语言」，方向完全正确。

七、utils / modules / locales 也是依赖图的一部分

打包报错时后面补进来的 utils、modules/i18n、locales 说明一个常见现实：你以为在迁移的是「组件」，实际上迁移的是「组件 + 它背后的运行支撑代码」。这类支撑代码不一起迁过来，组件库只会处在「看起来代码都在，实际上 build 一跑就断链」的状态。真正抽离组件库时，建议逐步画出「组件 → 工具 → 模块 → 资源」的依赖关系。

这一节最重要的工程结论不是「把所有错误都修完」，而是通过连续打包排错，把组件库的真实边界从模糊状态逼出来——哪些组件依赖太重、哪些依赖适合 external、哪些工具目录必须一起迁移、哪些动态导入会带来体积问题、哪些类型写法会撞到 SFC 编译器边界。这些信息比「把 build 跑通一次」更有价值。

常见问题

延伸阅读

• 上一篇：组件库局部引入方案：Element-Plus 自动按需解析
• 下一篇：组件库可用性验证：纯净 Playground 联调
• 相关：Vite Features: import.meta.glob
• 相关：Vue I18n Lazy Loading
• 相关：Element Plus Internationalization
• 相关：Vue compiler-sfc 复杂类型问题 #8355