03.6.2.2 组件库构建与 npm 发布
所属:全栈开发面试题库 / 03 前端基础与 Web 开发 / 03.6 前端工程化 / 03.6.2 Monorepo 与组件库发布
覆盖范围
- 构建工具:tsup、Vite Library 模式、rollup
- 双格式:ESM + CJS + 类型声明
- package.json:main/module/types/exports
- npm 发布:登录、tag、.npmignore、发布流程
- 样式:CSS 提取、CSS-in-JS、按需加载
高频题速览
| 编号 | 题目 | 难度 | 频率 |
|---|---|---|---|
| 03.6.2.2-001 | 组件库如何构建与发布 npm | 进阶 | ★★★★ |
| 03.6.2.2-002 | tsup 与 Vite Library 模式 | 进阶 | ★★★ |
| 03.6.2.2-003 | package.json exports 字段 | 进阶 | ★★★★ |
| 03.6.2.2-004 | 类型声明如何生成 | 进阶 | ★★★ |
| 03.6.2.2-005 | 样式如何随组件发布 | 进阶 | ★★★ |
| 03.6.2.2-006 | npm tag 与版本管理 | 基础 | ★★★ |
| 03.6.2.2-007 | peerDependencies 与 external | 进阶 | ★★★ |
| 03.6.2.2-008 | 发布前检查清单 | 基础 | ★★★ |
03.6.2.2-001 组件库如何构建与发布 npm
一句话结论
组件库构建输出 ESM + CJS + 类型声明 + 样式,配置 package.json 入口,npm publish 发布到 npm。
概念解释
- 构建:tsup/Vite。
- 发布:npm publish。
原理流程
- 构建输出 dist。
- 配置 package.json。
- npm login。
- npm publish。
代码 / 示例
tsup
npm publish
常见误区
- 误区:发布整个 src;正解:只发布 dist 与 README。
- 误区:忘记 types 字段;正解:TypeScript 项目必须配 types。
追问
- Q:如何首次发布? A:
npm publish --access public(scoped 包默认私有)。 - Q:如何撤回? A:
npm unpublish,24h 内可撤回。
03.6.2.2-002 tsup 与 Vite Library 模式
一句话结论
tsup 基于 esbuild,零配置快速打包 TS 库;Vite Library 模式用 Rollup 输出,适合需要控制 chunk 与样式的库。
概念解释
- tsup:esbuild 内核,快。
- Vite Library:Rollup 输出。
原理流程
- tsup 配置 entry/format/dts。
- Vite 用 build.lib 配置。
代码 / 示例
// tsup.config.ts
import { defineConfig } from "tsup";
export default defineConfig({
entry: ["src/index.ts"],
format: ["esm", "cjs"],
dts: true,
external: ["react"],
});
常见误区
- 误区:tsup 不能生成类型;正解:tsup 内置 dts,用 rollup-plugin-dts。
- 误区:Vite Library 与应用配置相同;正解:需要
build.lib与rollupOptions.external。
追问
- Q:如何选? A:TS 库用 tsup,需要复杂 chunk 用 Vite。
- Q:esbuild 不能生成 dts? A:是的,dts 用 tsc/rollup-plugin-dts。
03.6.2.2-003 package.json exports 字段
一句话结论
exports 是现代包入口字段,支持条件导出(import/require/types/default),子路径映射,比 main/module 更精确。
概念解释
- main:CJS 入口。
- module:ESM 入口(约定)。
- exports:标准条件导出。
原理流程
- 打包工具按条件选择入口。
- TypeScript 按 types 条件加载。
代码 / 示例
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
},
"./style.css": "./dist/style.css"
}
}
常见误区
- 误区:exports 与 main 同时存在冲突;正解:exports 优先级高于 main。
- 误区:exports 不支持子路径;正解:
./sub映射。
追问
- Q:Node 如何解析? A:Node 14+ 支持 exports。
- Q:bundler 如何处理? A:Vite/Webpack 都支持条件导出。
03.6.2.2-004 类型声明如何生成
一句话结论
用 tsc --emitDeclarationOnly 或 rollup-plugin-dts 从 TS 源生成 .d.ts;输出到 dist。
概念解释
- tsc:编译器生成声明。
- rollup-plugin-dts:合并多个 dts。
原理流程
- tsc 生成每个文件 dts。
- 合并为单文件。
代码 / 示例
tsc --emitDeclarationOnly --outDir dist
常见误区
- 误区:dts 与 JS 同时构建;正解:JS 用 esbuild,dts 用 tsc,分开。
- 误区:dts 不需要 external;正解:dts 引用 react 类型,需 external。
追问
- Q:如何打包 dts? A:tsup 内置 dts 用 rollup-plugin-dts。
- Q:types 字段指向哪里? A:
dist/index.d.ts。
03.6.2.2-005 样式如何随组件发布
一句话结论
样式方案:CSS-in-JS(运行时注入)、独立 CSS 文件(构建提取)、CSS Module;发布时样式随组件或单独引入。
概念解释
- CSS-in-JS:运行时。
- 独立 CSS:构建时提取。
原理流程
- CSS-in-JS 无需单独样式文件。
- 独立 CSS 输出到 dist。
代码 / 示例
{
"style": "./dist/style.css"
}
常见误区
- 误区:组件库必须自带样式;正解:CSS-in-JS 无需,CSS Module 需要。
- 误区:样式与 JS 混在一起;正解:现代库 CSS-in-JS 运行时注入。
追问
- Q:如何按需加载样式? A:CSS-in-JS 自动,独立 CSS 需要 babel-plugin-import。
- Q:暗色模式? A:CSS 变量,见 03.12.1。
03.6.2.2-006 npm tag 与版本管理
一句话结论
npm 默认 tag 是 latest,发布 beta 用 --tag beta,用户安装时 npm i pkg@beta;版本号用 semver。
概念解释
- tag:latest/beta/next。
- semver:major.minor.patch。
原理流程
npm publish --tag beta。npm dist-tag管理。
代码 / 示例
npm version patch
npm publish --tag beta
常见误区
- 误区:beta 版本号用 1.0.0-beta.0;正解:semver 预发布标签。
- 误区:tag 自动切换;正解:稳定后
npm dist-tag add pkg@version latest。
追问
- Q:如何发布 rc? A:
--tag next。 - Q:如何查看 tag? A:
npm dist-tag ls pkg。
03.6.2.2-007 peerDependencies 与 external
一句话结论
peerDependencies 标记宿主环境提供的依赖(如 react),external 让构建时不打包这些依赖。
概念解释
- peerDependencies:宿主必须安装。
- external:构建时排除。
原理流程
- peerDependencies 声明 react。
- 构建时 external: ["react"]。
- 用户安装时 react 已存在。
代码 / 示例
{
"peerDependencies": { "react": ">=18.0.0" }
}
常见误区
- 误区:react 打包进组件库;正解:会导致两份 react,冲突。
- 误区:peerDependencies 自动安装;正解:npm 7+ 自动安装,旧版本需手动。
追问
- Q:可选 peer 依赖? A:
peerDependenciesMeta: { "react-dom": { "optional": true } }。 - Q:external 与 alias 区别? A:external 不打包,alias 替换路径。
03.6.2.2-008 发布前检查清单
一句话结论
发布前:构建成功、类型无错、README 完整、.npmignore 排除 src、测试通过、版本号正确。
概念解释
- .npmignore:排除文件。
- files 字段:白名单。
原理流程
- CI 跑测试与构建。
- 检查 dist 内容。
- 发布。
代码 / 示例
{
"files": ["dist", "README.md"],
"scripts": { "prepublishOnly": "npm test && npm run build" }
}
常见误区
- 误区:发布整个仓库;正解:用 files 白名单。
- 误区:忘记 build;正解:prepublishOnly 自动跑。
追问
- Q:如何本地测试发布? A:
npm pack生成 tgz,本地安装测试。 - Q:如何自动发布? A:GitHub Actions + npm token。
03.6.2.2-009 bundle size 分析与 tree-shaking 验证
一句话结论
用 rollup-plugin-visualizer 或 source-map-explorer 分析 bundle;tree-shaking 要求 ESM 输出 + sideEffects 字段;验证方法是看产物中是否包含未使用代码。
概念解释
- tree-shaking:打包时移除未使用的导出。
- sideEffects:标记哪些文件有副作用,不能安全删除。
原理流程
- 构建时输出 ESM 格式(import/export)。
- 打包器静态分析,移除未引用导出。
- sideEffects 字段告诉打包器哪些文件不能 tree-shake。
代码 / 示例
{
"sideEffects": ["*.css", "esm/**/*.css"]
}
// vite.config.ts
import { visualizer } from "rollup-plugin-visualizer";
plugins: [visualizer({ open: true })]
常见误区
- 误区:CJS 也能 tree-shake;正解:CJS 动态 require 无法静态分析。
- 误区:sideEffects 设 false 就够;正解:CSS 文件必须标记为副作用。
追问
- Q:如何检查 tree-shaking 是否生效? A:visualizer 看未使用模块是否在产物中。
- Q:按需加载与 tree-shaking 区别? A:tree-shaking 是构建时删代码,按需加载是运行时分 chunk。
待整理清单
- [ ] 组件库文档站
- [ ] 组件单元测试
- [ ] 私有 npm 与 scoped 包
关联与延伸
- 与 03.6.2.1 Monorepo 配合,Monorepo 中组件库发布是常见场景。
- 与 03.12.2 组件库工程配合,本节聚焦构建与发布流程。
- exports 字段是现代 npm 包的标配,需掌握条件导出。
面试准备要点
- 必须说清组件库构建输出:ESM + CJS + 类型声明 + 样式。
- 必须理解 exports 字段:条件导出,优先级高于 main。
- 常见追问:peerDependencies 作用?答:宿主提供,避免打包多份 react。
- 常见追问:tsup 与 Vite Library 区别?答:tsup 快,Vite 控制细。
- 常见追问:npm tag 作用?答:latest/beta,用户安装时选择。
- 常见追问:如何发布 scoped 包?答:
npm publish --access public。 - 常见追问:如何本地测试发布?答:
npm pack生成 tgz 本地安装。 - 常见追问:peerDependencies 与 external?答:声明宿主提供,构建时排除。
- 常见追问:types 字段指向哪里?答:
dist/index.d.ts。 - 常见追问:组件库构建输出?答:ESM + CJS + 类型声明 + 样式。
- 常见追问:npm tag 作用?答:latest/beta,用户安装时选择。
- 常见追问:如何本地测试发布?答:
npm pack生成 tgz 本地安装。