写在前面在完成了核心组件的开发后我们的组件库my-antd-ui正式进入了最关键的阶段——工程化完善。这不仅是把代码传到网上那么简单更是要建立一套标准、稳定、自动化的生产体系。为你深度拆解生产级组件库的打包构建流程。 发布前的四大核心命题之前的开发都停留在“本地跑通”阶段。要成为一个真正的“企业级开源产品”我们需要回答以下四个核心命题如何统一打包解决产物从源码向编译代码的进化如何建立包依赖解决内部包联调与第三方库冲突如何统一测试建立全自动的代码质量守卫如何发布实现规范的版本管理与自动化流水线本文上篇将围绕“统一打包、包依赖建立、统一测试”这三个核心命题为你深度拆解生产级组件库的构建全流程。一、如何统一打包效率篇在 Monorepo 这种复杂的环境下我们不能手动进入每个文件夹打包。1. 一键构建Monorepo 的魔力由于我们的项目是 Monorepo 结构子包非常多。为了不用一个个进入子目录打包我们在根目录配置了“一键构建”脚本// my-antd-ui/package.jsonscripts:{build:pnpm -r --filter \./packages/**\ run build}pnpm -r(recursive)递归模式告诉 pnpm 去所有的子包里跑命令。--filter ./packages/**过滤器精准锁定packages目录下的所有包。作用只需在根目录运行一次pnpm build它就会自动帮我们将所有组件打包好。2. package.json 的进化从源码到产物你可能会发现packages/components/package.json的入口配置发生了变化这其实是它的“发布声明”{name:my-antd-ui/components,main:dist/index.js,module:dist/index.mjs,types:dist/types/index.d.ts,exports:{.:{types:./dist/types/index.d.ts,import:./dist/index.mjs,require:./dist/index.js}},peerDependencies:{vue:^3.0.0},dependencies:{ant-design-vue:^4.2.6}}关键字段解析mainmodule分别对应 CommonJS 和 ESM 两种规范。确保你的库既能在老项目中跑也能在现代 Vite 项目中享受Tree Shaking的瘦身效果。types(或typings)指定了“补全说明书”的路径。没有它用户写代码时就没有类型提示。exports现代 Node.js 的标准。它能智能识别用户的引入方式是import还是require并分发最合适的文件。peerDependenciesvsdependencies同辈依赖 (Peer)如vue。我们不希望把 Vue 打包进去而是要求用户自己安装以保证全局只有一个 Vue 实例避免响应式断开。运行依赖 (Deps)如ant-design-vue。这是库运行必须的用户安装时会自动下载。3. 库模式基础配置与普通项目打包输出 HTML 不同库模式的目标是产出 JS 文件。核心配置如下// packages/components/vite.config.tsbuild:{lib:{// 1. 指定入口文件通常是 index.tsentry:resolve(__dirname,index.ts),// 2. 库的全局变量名称用于 UMD/CDN 引入name:MyAntdUiComponents,// 3. 输出的文件名fileName:index,// 4. 导出的格式ESM (现代) 和 CJS (Node.js)formats:[es,cjs]}}4. 核心配置external与globals配置好库模式后我们还需要处理依赖项这是两个“保命配置”// packages/components/vite.config.tsrollupOptions:{// 1. 外部化依赖不打包进产物中external:[vue,my-antd-ui/utils,ant-design/icons-vue,ant-design-vue],output:{// 2. 在 UMD 模式下为这些外部依赖提供全局变量映射globals:{vue:Vue,ant-design-vue:Antd}}}External (外部化)我们把vue、ant-design-vue等设为外部依赖。原理告诉打包工具“这些东西用户家里肯定有别塞进我的包里”。后果如果不配置你的包里会含有一套 Vue 源码。当用户使用时页面上会有两个 Vue 实例直接导致响应式失效数据变了页面没反应。Globals (全局变量)为 UMD/CDN 引入提供“翻译表”。背景当用户不使用 Vite 或 Webpack而是直接在 HTML 里通过script标签引入你的库时浏览器环境是没有模块系统的。通俗解释你的代码里写着import { ref } from vue但浏览器在全局环境里根本找不到一个叫vue的模块。它只认识全局变量比如window.Vue。作用globals: { vue: Vue }这行配置就像是一张翻译表告诉浏览器“代码里凡是提到vue的地方请直接去全局变量window.Vue里面取”。如果没有这个配置浏览器会因为找不到vue而直接报错。5. 类型文件的“自动吐出”我们集成了vite-plugin-dts。如果没有它用户在使用你的组件库时IDE 里将没有任何代码提示。// packages/components/vite.config.tsdts({// 1. 包含的文件范围告诉插件哪些文件需要生成类型include:[src/**/*.ts,src/**/*.vue,index.ts],// 2. 类型文件输出目录统一存放在 dist/types 下outDir:dist/types})include就像是给插件画了个“生产圈”。它不仅处理.ts文件还能自动提取.vue组件中script setup里的 Props 和 Emits 定义非常智能。outDir指定存放位置。配合package.json中的types: dist/types/index.d.ts用户在写代码时VSCode 就能顺着这个路径找到“补全说明书”。Tips这确保了用户在引入你的库时能享受到 TypeScript 带来的精准类型检查和秒级代码补全。4.1 实战中的“填坑”干货在工程化过程中我们总结了两个“保命配置”External在 Vite 打包时将 Vue 排除在外防止重复打包导致应用崩溃。Global.d.ts通过 TS 的声明合并Module Augmentation让用户在写代码时能享受到完美的自动补全提示。总结工程化不是把事情变复杂而是为了让复杂的协作变得简单、标准、自动化。关联文件打包配置packages/components/vite.config.ts全局提示packages/components/global.d.ts6. 完整的构建配置文件示例为了方便大家参考这里贴出packages/components/vite.config.ts的完整代码import{dirname,resolve}fromnode:pathimport{fileURLToPath}fromnode:urlimportvuefromvitejs/plugin-vueimport{defineConfig}fromviteimportdtsfromvite-plugin-dts// 获取当前文件的绝对路径解决 ESM 环境下 __dirname 缺失的问题const__dirnamedirname(fileURLToPath(import.meta.url))exportdefaultdefineConfig({plugins:[// 处理 .vue 文件vue(),// 自动生成 .d.ts 类型定义文件dts({// 包含的文件范围include:[src/**/*.ts,src/**/*.vue,index.ts],// 类型文件输出目录outDir:dist/types})]asany,// 解决 monorepo 中多版本 vite 导致的插件类型冲突build:{// 库模式配置lib:{// 入口文件entry:resolve(__dirname,index.ts),// 暴露的全局变量名称用于 UMD 构建name:MyAntdUiComponents,// 输出的文件名fileName:index,// 导出的格式formats:[es,cjs]},rollupOptions:{// 外部化依赖不打包进产物中减小体积并避免多版本冲突external:[vue,my-antd-ui/utils,ant-design/icons-vue,ant-design-vue],output:{// 在 UMD 模式下为 these 外部依赖提供全局变量映射globals:{vue:Vue,ant-design-vue:Antd}}}}})7. 开发者体验Volar 提示补全为了让用户在 VSCode 中像使用Element Plus一样丝滑我们编写了global.d.ts。7.1. 为什么需要 global.d.ts在 Vue3 中如果你全局注册了组件例如通过app.use(MyUI)在.vue文件的模板中使用这些组件时编辑器VSCode默认是没有任何提示的。这会导致开发者不知道有哪些props可以传极大降低开发效率。7.2. 原理解析与代码逐行拆解我们通过扩展 Vue 的核心接口来解决这个问题// packages/components/global.d.ts// 1. 必须先 import定位到我们要修改的“Vue 总部大楼”importvue/runtime-core// 2. 进入大楼宣布我们要进行“二次装修”declaremodulevue/runtime-core{// 3. 核心扩展 Volar 插件专用的全局组件接口exportinterfaceGlobalComponents{// 4. 映射[标签名]: (从已定义的组件中自动抓取类型)MyButton:(typeofimport(my-antd-ui/components))[MyButton]MyInput:(typeofimport(my-antd-ui/components))[MyInput]MyIcon:(typeofimport(my-antd-ui/components))[MyIcon]MyRow:(typeofimport(my-antd-ui/components))[MyRow]MyCol:(typeofimport(my-antd-ui/components))[MyCol]MyVirtualList:(typeofimport(my-antd-ui/components))[MyVirtualList]}}// 5. 确保该文件被视为一个独立的模块防止类型污染export{}逐行理解import vue/runtime-core这是模块扩展 (Module Augmentation)的前提。它告诉 TypeScript 我们要寻找并修改的是已存在的模块而不是定义一个全新的空模块。declare module vue/runtime-core这是“二次装修”的开始通过该声明我们可以向已有的 Vue 核心类型中注入自定义的组件类型映射。GlobalComponents接口这是 IDE 提示的“水源”。Volar 插件会实时监控这个接口一旦你把组件名塞进去它就能在模板中为你提供自动补全、属性校验和悬浮文档。typeof import(...)这是一种极其智能的写法。它不需要你手动维护类型而是会自动同步你组件源码中的所有props、emits和slots定义。export {}确保该文件被视为一个独立的模块符合现代 TS 项目的标准规范。7.3. 它是怎么生效的底层机制这套机制的背后依赖于 TypeScript 的两个核心能力声明合并 (Declaration Merging)通过declare module我们并没有替换 Vue 的类型而是将我们的组件类型“追加”到了 Vue 原有的全局组件清单中。自动扫描与识别TypeScript 和 Volar 插件会自动扫描项目中的声明文件.d.ts。只要这个文件被包含在 TypeScript 的检测范围内编辑器就能实时识别出模板中的全局标签。二、如何建立包依赖架构篇组件库内部往往有很多关联比如components依赖utils。内部联调workspace 协议在packages/components/package.json中dependencies:{my-antd-ui/utils:workspace:*,ant-design-vue:^4.2.6}workspace:*这是关键它告诉 pnpm 优先找项目本地的utils包而不是去 npm 下载。PeerDependencies我们将vue设为同辈依赖。这确保了用户的项目里只有一份 Vue 实例避免了响应式失效的致命问题。三、如何统一测试质量篇我们要确保每一次发布的代码都是稳如泰山的。自动化防线Vitest GitHub Actions统一脚本根目录配置test: vitest一键扫描全库所有组件的测试用例。CI 门禁在.github/workflows/ci.yml中我们规定每当代码 Push 到 GitHub自动运行pnpm lint查错。自动运行pnpm test验证功能。双端同步镜像为了让国内用户访问更快我们还通过 Actions 自动将代码同步镜像到Gitee。 结语上篇通过本文我们完成了组件库工程化构建的三大支柱统一打包、内部依赖关联以及自动化测试体系。接下来在《从本地到 NPM下版本管理与自动化发布指南》中我们将深入探讨如何利用 Changesets 管理版本并实现组件库在 NPM 的正式发布。
Vue3 组件库实战(六)：从本地到 NPM，Vue 组件库工程化构建与打包全指南（上）
写在前面在完成了核心组件的开发后我们的组件库my-antd-ui正式进入了最关键的阶段——工程化完善。这不仅是把代码传到网上那么简单更是要建立一套标准、稳定、自动化的生产体系。为你深度拆解生产级组件库的打包构建流程。 发布前的四大核心命题之前的开发都停留在“本地跑通”阶段。要成为一个真正的“企业级开源产品”我们需要回答以下四个核心命题如何统一打包解决产物从源码向编译代码的进化如何建立包依赖解决内部包联调与第三方库冲突如何统一测试建立全自动的代码质量守卫如何发布实现规范的版本管理与自动化流水线本文上篇将围绕“统一打包、包依赖建立、统一测试”这三个核心命题为你深度拆解生产级组件库的构建全流程。一、如何统一打包效率篇在 Monorepo 这种复杂的环境下我们不能手动进入每个文件夹打包。1. 一键构建Monorepo 的魔力由于我们的项目是 Monorepo 结构子包非常多。为了不用一个个进入子目录打包我们在根目录配置了“一键构建”脚本// my-antd-ui/package.jsonscripts:{build:pnpm -r --filter \./packages/**\ run build}pnpm -r(recursive)递归模式告诉 pnpm 去所有的子包里跑命令。--filter ./packages/**过滤器精准锁定packages目录下的所有包。作用只需在根目录运行一次pnpm build它就会自动帮我们将所有组件打包好。2. package.json 的进化从源码到产物你可能会发现packages/components/package.json的入口配置发生了变化这其实是它的“发布声明”{name:my-antd-ui/components,main:dist/index.js,module:dist/index.mjs,types:dist/types/index.d.ts,exports:{.:{types:./dist/types/index.d.ts,import:./dist/index.mjs,require:./dist/index.js}},peerDependencies:{vue:^3.0.0},dependencies:{ant-design-vue:^4.2.6}}关键字段解析mainmodule分别对应 CommonJS 和 ESM 两种规范。确保你的库既能在老项目中跑也能在现代 Vite 项目中享受Tree Shaking的瘦身效果。types(或typings)指定了“补全说明书”的路径。没有它用户写代码时就没有类型提示。exports现代 Node.js 的标准。它能智能识别用户的引入方式是import还是require并分发最合适的文件。peerDependenciesvsdependencies同辈依赖 (Peer)如vue。我们不希望把 Vue 打包进去而是要求用户自己安装以保证全局只有一个 Vue 实例避免响应式断开。运行依赖 (Deps)如ant-design-vue。这是库运行必须的用户安装时会自动下载。3. 库模式基础配置与普通项目打包输出 HTML 不同库模式的目标是产出 JS 文件。核心配置如下// packages/components/vite.config.tsbuild:{lib:{// 1. 指定入口文件通常是 index.tsentry:resolve(__dirname,index.ts),// 2. 库的全局变量名称用于 UMD/CDN 引入name:MyAntdUiComponents,// 3. 输出的文件名fileName:index,// 4. 导出的格式ESM (现代) 和 CJS (Node.js)formats:[es,cjs]}}4. 核心配置external与globals配置好库模式后我们还需要处理依赖项这是两个“保命配置”// packages/components/vite.config.tsrollupOptions:{// 1. 外部化依赖不打包进产物中external:[vue,my-antd-ui/utils,ant-design/icons-vue,ant-design-vue],output:{// 2. 在 UMD 模式下为这些外部依赖提供全局变量映射globals:{vue:Vue,ant-design-vue:Antd}}}External (外部化)我们把vue、ant-design-vue等设为外部依赖。原理告诉打包工具“这些东西用户家里肯定有别塞进我的包里”。后果如果不配置你的包里会含有一套 Vue 源码。当用户使用时页面上会有两个 Vue 实例直接导致响应式失效数据变了页面没反应。Globals (全局变量)为 UMD/CDN 引入提供“翻译表”。背景当用户不使用 Vite 或 Webpack而是直接在 HTML 里通过script标签引入你的库时浏览器环境是没有模块系统的。通俗解释你的代码里写着import { ref } from vue但浏览器在全局环境里根本找不到一个叫vue的模块。它只认识全局变量比如window.Vue。作用globals: { vue: Vue }这行配置就像是一张翻译表告诉浏览器“代码里凡是提到vue的地方请直接去全局变量window.Vue里面取”。如果没有这个配置浏览器会因为找不到vue而直接报错。5. 类型文件的“自动吐出”我们集成了vite-plugin-dts。如果没有它用户在使用你的组件库时IDE 里将没有任何代码提示。// packages/components/vite.config.tsdts({// 1. 包含的文件范围告诉插件哪些文件需要生成类型include:[src/**/*.ts,src/**/*.vue,index.ts],// 2. 类型文件输出目录统一存放在 dist/types 下outDir:dist/types})include就像是给插件画了个“生产圈”。它不仅处理.ts文件还能自动提取.vue组件中script setup里的 Props 和 Emits 定义非常智能。outDir指定存放位置。配合package.json中的types: dist/types/index.d.ts用户在写代码时VSCode 就能顺着这个路径找到“补全说明书”。Tips这确保了用户在引入你的库时能享受到 TypeScript 带来的精准类型检查和秒级代码补全。4.1 实战中的“填坑”干货在工程化过程中我们总结了两个“保命配置”External在 Vite 打包时将 Vue 排除在外防止重复打包导致应用崩溃。Global.d.ts通过 TS 的声明合并Module Augmentation让用户在写代码时能享受到完美的自动补全提示。总结工程化不是把事情变复杂而是为了让复杂的协作变得简单、标准、自动化。关联文件打包配置packages/components/vite.config.ts全局提示packages/components/global.d.ts6. 完整的构建配置文件示例为了方便大家参考这里贴出packages/components/vite.config.ts的完整代码import{dirname,resolve}fromnode:pathimport{fileURLToPath}fromnode:urlimportvuefromvitejs/plugin-vueimport{defineConfig}fromviteimportdtsfromvite-plugin-dts// 获取当前文件的绝对路径解决 ESM 环境下 __dirname 缺失的问题const__dirnamedirname(fileURLToPath(import.meta.url))exportdefaultdefineConfig({plugins:[// 处理 .vue 文件vue(),// 自动生成 .d.ts 类型定义文件dts({// 包含的文件范围include:[src/**/*.ts,src/**/*.vue,index.ts],// 类型文件输出目录outDir:dist/types})]asany,// 解决 monorepo 中多版本 vite 导致的插件类型冲突build:{// 库模式配置lib:{// 入口文件entry:resolve(__dirname,index.ts),// 暴露的全局变量名称用于 UMD 构建name:MyAntdUiComponents,// 输出的文件名fileName:index,// 导出的格式formats:[es,cjs]},rollupOptions:{// 外部化依赖不打包进产物中减小体积并避免多版本冲突external:[vue,my-antd-ui/utils,ant-design/icons-vue,ant-design-vue],output:{// 在 UMD 模式下为 these 外部依赖提供全局变量映射globals:{vue:Vue,ant-design-vue:Antd}}}}})7. 开发者体验Volar 提示补全为了让用户在 VSCode 中像使用Element Plus一样丝滑我们编写了global.d.ts。7.1. 为什么需要 global.d.ts在 Vue3 中如果你全局注册了组件例如通过app.use(MyUI)在.vue文件的模板中使用这些组件时编辑器VSCode默认是没有任何提示的。这会导致开发者不知道有哪些props可以传极大降低开发效率。7.2. 原理解析与代码逐行拆解我们通过扩展 Vue 的核心接口来解决这个问题// packages/components/global.d.ts// 1. 必须先 import定位到我们要修改的“Vue 总部大楼”importvue/runtime-core// 2. 进入大楼宣布我们要进行“二次装修”declaremodulevue/runtime-core{// 3. 核心扩展 Volar 插件专用的全局组件接口exportinterfaceGlobalComponents{// 4. 映射[标签名]: (从已定义的组件中自动抓取类型)MyButton:(typeofimport(my-antd-ui/components))[MyButton]MyInput:(typeofimport(my-antd-ui/components))[MyInput]MyIcon:(typeofimport(my-antd-ui/components))[MyIcon]MyRow:(typeofimport(my-antd-ui/components))[MyRow]MyCol:(typeofimport(my-antd-ui/components))[MyCol]MyVirtualList:(typeofimport(my-antd-ui/components))[MyVirtualList]}}// 5. 确保该文件被视为一个独立的模块防止类型污染export{}逐行理解import vue/runtime-core这是模块扩展 (Module Augmentation)的前提。它告诉 TypeScript 我们要寻找并修改的是已存在的模块而不是定义一个全新的空模块。declare module vue/runtime-core这是“二次装修”的开始通过该声明我们可以向已有的 Vue 核心类型中注入自定义的组件类型映射。GlobalComponents接口这是 IDE 提示的“水源”。Volar 插件会实时监控这个接口一旦你把组件名塞进去它就能在模板中为你提供自动补全、属性校验和悬浮文档。typeof import(...)这是一种极其智能的写法。它不需要你手动维护类型而是会自动同步你组件源码中的所有props、emits和slots定义。export {}确保该文件被视为一个独立的模块符合现代 TS 项目的标准规范。7.3. 它是怎么生效的底层机制这套机制的背后依赖于 TypeScript 的两个核心能力声明合并 (Declaration Merging)通过declare module我们并没有替换 Vue 的类型而是将我们的组件类型“追加”到了 Vue 原有的全局组件清单中。自动扫描与识别TypeScript 和 Volar 插件会自动扫描项目中的声明文件.d.ts。只要这个文件被包含在 TypeScript 的检测范围内编辑器就能实时识别出模板中的全局标签。二、如何建立包依赖架构篇组件库内部往往有很多关联比如components依赖utils。内部联调workspace 协议在packages/components/package.json中dependencies:{my-antd-ui/utils:workspace:*,ant-design-vue:^4.2.6}workspace:*这是关键它告诉 pnpm 优先找项目本地的utils包而不是去 npm 下载。PeerDependencies我们将vue设为同辈依赖。这确保了用户的项目里只有一份 Vue 实例避免了响应式失效的致命问题。三、如何统一测试质量篇我们要确保每一次发布的代码都是稳如泰山的。自动化防线Vitest GitHub Actions统一脚本根目录配置test: vitest一键扫描全库所有组件的测试用例。CI 门禁在.github/workflows/ci.yml中我们规定每当代码 Push 到 GitHub自动运行pnpm lint查错。自动运行pnpm test验证功能。双端同步镜像为了让国内用户访问更快我们还通过 Actions 自动将代码同步镜像到Gitee。 结语上篇通过本文我们完成了组件库工程化构建的三大支柱统一打包、内部依赖关联以及自动化测试体系。接下来在《从本地到 NPM下版本管理与自动化发布指南》中我们将深入探讨如何利用 Changesets 管理版本并实现组件库在 NPM 的正式发布。
