用Vite从零搭建Vue3组件库并发布到npm的完整流程。

当你想做个组件库，而不是又写一遍业务代码

前端干久了，总有一种冲动：把常用的按钮、弹窗、表单封装成自己的组件库，放到 npm 上，下次开新项目直接 npm install 一把梭。但真到动手时，很多人卡在「怎么搭工程」「怎么出类型」「怎么发布」这三座大山前。Vite 的出现让这件事变得简单得不像话——今天就带你从零到一，走一遍完整流程。

初始化工程，选对构建配置

别用 vite create 那种标准模板，因为我们是组件库，不是应用。手动建个目录，npm init -y 后装依赖：

npm install vue@3
npm install -D vite @vitejs/plugin-vue vite-plugin-dts

重点是 Vite 的构建配置。组件的入口不能是 index.html，而是我们的组件源码。在 vite.config.ts 里用 build.lib 模式：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import dts from 'vite-plugin-dts'

export default defineConfig({
  plugins: [vue(), dts({ include: ['src'], outDir: 'dist/types' })],
  build: {
    lib: {
      entry: 'src/index.ts',
      name: 'MyUI',
      formats: ['es', 'umd'],
      fileName: (format) => `my-ui.${format}.js`
    },
    rollupOptions: {
      external: ['vue'],
      output: {
        globals: { vue: 'Vue' }
      }
    }
  }
})

把 vue 设为 external 至关重要，否则会把整个 Vue 打包进组件库，导致使用方重复加载。vite-plugin-dts 负责自动生成 .d.ts 类型声明，这才是 Vue3 组件库的硬通货。

组件写得好，但别把样式锁死

组件库的核心不是把代码塞进 src/components 就完事。推荐目录结构：

src/
  index.ts       // 统一导出
  button/
    Button.vue
    index.ts
  modal/
    Modal.vue
    index.ts

每个组件的 index.ts 里加上 withInstall 方法——这是组件库的惯例，让用户既可以用 <MyButton>，也可以 app.use(MyButton) 全局注册：

import type { App } from 'vue'
import Button from './Button.vue'

Button.install = (app: App) => {
  app.component(Button.name, Button)
}

export default Button as typeof Button & { install: (app: App) => void }

样式方面，建议用 SCSS 变量 + CSS 自定义属性（CSS Variables）双轨制。CSS 变量可以避免用户覆写样式时被深层的 scoped 选择器卡住。不要用 scoped，而是用统一的 BEM 类名前缀，比如 my-button、my-button--primary。

发布前最后的魔鬼细节

打包完成后，dist 目录会生成 ESM 和 UMD 文件，但真正的考验在 package.json：

{
  "name": "@yourname/my-ui",
  "version": "0.1.0",
  "main": "dist/my-ui.umd.js",
  "module": "dist/my-ui.es.js",
  "types": "dist/types/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/my-ui.es.js",
      "require": "./dist/my-ui.umd.js",
      "types": "./dist/types/index.d.ts"
    },
    "./style.css": "./dist/my-ui.css"
  },
  "files": ["dist"],
  "peerDependencies": {
    "vue": "^3.2.0"
  }
}

注意 peerDependencies 声明 Vue 为同行依赖，files 只打包 dist，别把源码和 node_modules 一起推上去。exports 字段是 Node12+ 和现代打包器解析的入口，写不好会让人无法 import 样式。

样式文件怎么出？Vite 默认会把所有被引用的 CSS 抽成一个 style.css。但组件库更讲究「按需加载」，建议在组件内部直接 import './Button.css'，再用 build.cssCodeSplit 开启代码分割。不过对新手而言，一个全量 CSS 先跑通流程更重要。

验证打包，然后发布

发布前必须做本地验证。在 dist 目录同级开个测试项目，用 npm link 把组件库链过去，写个 App.vue 测试按需注册、全局注册、样式引入。这一步能避免发到 npm 上才发现组件根本渲染不出来——别问我怎么知道的。

一切就绪后，执行：

npm login
npm publish --access public

如果你用的是私有 npm 包名，比如 @mycompany/ui，不需要 --access public，但公共包必须加。

维护比构建更值得关注

流程跑通了，你会发现自己陷入另一个循环：每次改组件代码都要重新打包、更新版本号、再发布。建议用 changesets 管理版本更新，或者在 commit 信息里带 fix:, feat: 前缀配合 semantic-release 自动发版。组件库不是一次性的任务，而是需要长期维护的工程。

最后提醒一句：component library is easy, component design is hard。别本末倒置，先在业务里沉淀几个反复使用组件，把它们抽出来打磨成真正解决痛点的工具，然后才用上面这套流程交给全世界。Vite 帮你扫清了工具链的障碍，剩下的就看你的审美和对场景的理解了。