Vue 3 用 Vite 库模式打包组件并发布到 npm：类型声明、tree-shaking 与产物校验

为什么走库模式而不是应用构建

当你想把一组 Vue 组件或组合式函数交付给别的团队、或开源出去，最干净的方式是打成一个 npm 包，而不是一个整站。Vite 的“库模式”专门为此设计：它不生成带 HTML 入口的应用，而是直接把你的模块编译成可被 import 的 ES 与 CJS 产物。

配置 vite.config.ts

核心是 build.lib 字段。多入口时用对象形式，并且要把 vue 标记为外部依赖，避免把整个 Vue 打进包里。

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { resolve } from "path";

export default defineConfig({
  plugins: [vue()],
  build: {
    lib: {
      entry: resolve(__dirname, "src/index.ts"),
      name: "MyUi",
      fileName: "my-ui",
      formats: ["es", "cjs"],
    },
    rollupOptions: {
      external: ["vue"],
      output: {
        globals: { vue: "Vue" },
        exports: "named",
      },
    },
  },
});

导出入口与样式

在 src/index.ts 里统一导出组件、类型与样式，保持对外 API 简洁。

import MyButton from "./components/MyButton.vue";
import MyModal from "./components/MyModal.vue";

export { MyButton, MyModal };
export type { ButtonProps } from "./types";

import "./style.css";

生成类型声明

Vite 本身不产出 .d.ts，需要配合 vue-tsc。在 package.json 里把脚本串起来。

{
  "scripts": {
    "build": "vue-tsc --declaration --emitDeclarationOnly && vite build",
    "prepublishOnly": "npm run build"
  },
  "files": ["dist"],
  "main": "./dist/my-ui.cjs",
  "module": "./dist/my-ui.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/my-ui.js",
      "require": "./dist/my-ui.cjs"
    }
  }
}

发布前检查清单

• external 必须包含 vue 及所有想让使用方自己提供的依赖，否则产物会重复打包、tree-shaking 也失效。
• exports 字段比 main/module 更现代，使用方用 ESM 或 CJS 都能正确解析。
• 在副作用样式上谨慎：如果样式靠副作用引入，使用方可能需要显式导入，文档里要写清楚。
• 本地先用 npm pack 生成 tgz，再 npm install 到测试项目验证，最后才 npm publish。

这样打出来的包体积小、类型完整，别人用 npm i 装上就能直接 import 你的 Vue 组件。