Vite 库模式

除了做应用，Vite 也能打包可复用的库（组件库、工具函数集等）。这一篇我们讲库模式（Library Mode）的用法和发布流程。

什么是库模式

默认 vite build 假设你构建一个「应用」，入口是 index.html，产出是一堆带 HTML 的静态站点。库模式则反过来，入口是一个 JS 文件，产出是供别人 import 的库文件，不需要 HTML。

当你想把自己的组件或工具发布到 npm 给别人用时，就该用库模式。

build.lib 配置详解

在 vite.config.js 里用 build.lib 声明入口和库名：

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

export default defineConfig({
  plugins: [vue()],
  build: {
    lib: {
      entry: 'src/index.js',   // 库的入口文件
      name: 'MyLib',           // 全局变量名（UMD 用）
      fileName: (format) => `my-lib.${format}.js`
    }
  }
})

entry 指向你的库主文件，name 是给 UMD 格式用的全局名，fileName 决定产物文件名。

入口与导出组织

库入口一般集中导出所有对外 API，方便使用者按需引入：

// src/index.js
export { default as Button } from './components/Button.vue'
export { formatDate } from './utils/date.js'
export function greet(name) {
  return `Hello ${name}`
}

使用者就能这样用：

import { Button, formatDate } from 'my-lib'

处理外部依赖 external

打包库时，通常不想把 Vue、React 这类框架打进你的库里，否则使用者会重复加载两份。用 rollupOptions.external 把它们标记为外部依赖：

export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.js',
      name: 'MyLib',
      fileName: (format) => `my-lib.${format}.js`
    },
    rollupOptions: {
      external: ['vue'],
      output: {
        globals: {
          vue: 'Vue'
        }
      }
    }
  }
})

external: ['vue'] 告诉打包器不要把 vue 打进来；globals 告诉 UMD 格式 vue 对应的全局变量名。

生成多种格式

同时产出 ESM 和 UMD 两种格式，能兼顾现代打包器和传统 <script> 引入：

build: {
  lib: {
    entry: 'src/index.js',
    name: 'MyLib',
    formats: ['es', 'umd'],
    fileName: (format) => `my-lib.${format}.js`
  }
}

• ESM（es）供 Vite、webpack 等现代工具 import。
• UMD（umd）供直接在浏览器 <script> 里用，或老项目。

发布到 npm 的流程

第一步，确保 package.json 正确声明产物和入口：

{
  "name": "my-lib",
  "version": "0.1.0",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/my-lib.umd.js",
  "module": "./dist/my-lib.es.js",
  "exports": {
    ".": {
      "import": "./dist/my-lib.es.js",
      "require": "./dist/my-lib.umd.js"
    }
  }
}

第二步，构建：

npm run build

第三步，登录并发布（需要先在 npm 官网注册账号）：

npm login
npm publish

如果是第一次发布，注意包名不能和别人重复，且不要把密钥、测试文件误带进去。files 字段控制只发布 dist，避免源码泄露。

本篇小结

• 库模式用 build.lib 指定入口，产出供 import 的库而非站点。
• 用 external 把框架排除，避免重复打包。
• formats 可同时产出 ESM 与 UMD 适配不同场景。
• package.json 的 exports 正确配置后就能 npm publish。

下一篇是实战，我们用一个完整项目把前面所有知识串起来。