Vite 库模式打包：从基础配置到产物体积优化

把内部组件库从 webpack 迁到 Vite 的库模式，记录配置要点和踩过的坑。

build.lib 基础配置

export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.ts',
      formats: ['es', 'umd'],
      fileName: (format) => `widget.${format}.js`
    }
  }
})

库模式下 Vite 只做打包不做 HTML 注入，产物是纯 JS。UMG 格式注意 name 配置，它决定全局变量名。

external：别把依赖打进去

react、react-dom 这类 peerDependencies 必须 external，否则依赖会被打进产物：体积膨胀是小事，多实例导致 hooks 报错是大事。

build: {
  rollupOptions: {
    external: ['react', 'react-dom'],
    output: { globals: { react: 'React', 'react-dom': 'ReactDOM' } }
  }
}

体积优化

• 按需引入：package.json 加 sideEffects: false，保持命名导出；
• sourcemap 只保留在内部版本，对外发布关闭；
• 用 rollup-plugin-visualizer 看 gzip 前后的体积构成，优先砍大依赖。

CSS 怎么办

库模式下 CSS 默认被注入进 JS，运行时动态创建 style 标签。更好的做法是提供一个独立样式入口 style.css，让使用者二选一，避免样式重复注入。

小结

库模式本身配置不多，真正花时间的是产物策略：external 边界、按需能力和 CSS 注入方式，这些决定了使用方接入的体验。