前端组件库怎么搭建和发布到 npm？package.json 需要配置哪些字段？

Question

仓乃文 · Accepted Answer

组件库发布到 npm 最大的坑不是代码本身，而是 package.json 的字段配置错误导致消费者无法正确引入。main/module/exports/types 这四个字段必须配齐，否则要么引入报错，要么类型丢失。

package.json 关键字段：
```json
{
  "name": "my-ui-lib",
  "version": "1.0.0",
  "private": false,
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.cjs.js",
      "types": "./dist/index.d.ts"
    },
    "./style.css": "./dist/style.css"
  },
  "files": ["dist"],
  "sideEffects": ["*.css"],
  "peerDependencies": {
    "vue": ">=3.0.0"
  },
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/"
  }
}
```

Vite 库模式构建配置：
```typescript
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: "MyUILib",
      formats: ["es", "cjs"],
      fileName: (format) => `index.${format === "es" ? "esm" : "cjs"}.js`,
    },
    rollupOptions: {
      external: ["vue"],
      output: {
        globals: { vue: "Vue" },
      },
    },
  },
});
```

发布流程：
```bash
# 1. 构建
pnpm build

# 2. 检查将要发布的文件
npm pack --dry-run

# 3. 登录 npm
npm login

# 4. 发布
npm publish

# scoped 包首次发布需要：
npm publish --access public
```

补充说明：
- main 是 CJS 入口，module 是 ESM 入口，exports 是 Node 12+ 的现代入口，优先级最高
- files 字段控制哪些文件被发布，避免把 src 和测试文件发上去
- peerDependencies 不要放 dependencies 里，否则消费者会重复安装 Vue
- 用 npm pack --dry-run 预览发布内容，避免发布不必要的文件