从本地到 NPM（下）：版本管理与自动化发布指南
写在前面：在完成了核心组件的打包构建与测试后（详见《从本地到 NPM（上）：工程化构建与打包指南》），我们的组件库
my-antd-ui正式进入了最后也是最关键的阶段——版本发布。这不仅是把代码传到网上那么简单，更是要建立一套规范、透明、可回溯的版本管理体系。
四、如何发布？（流程篇）
手动改版本号和写更新日志太低效。在 Monorepo 项目中，手动管理几十个子包的版本号简直是噩梦。我们引入了版本管理利器：Changesets。
1. 什么是 Changesets？
它是一个专门处理版本控制和变更记录的工具。它将“记录改动”与“执行发布”解耦，让版本迭代变得像流水线一样精准。
2. 为什么我们需要它？
- 拒绝手动修改：不用再去每个
package.json里手动填版本号。 - 自动化日志：它会自动收集你的改动信息，生成漂亮的
CHANGELOG.md。 - 关联性同步：如果你改了
utils包，它会自动提醒你受影响的components包是否也需要升级。
3. 核心配置速览
我们的配置文件位于 .changeset/config.json，它是整个发布系统的“大脑”：
{
"$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
"changelog": "@changesets/cli/changelog", // 指定生成 CHANGELOG.md 的方式
"commit": false, // 执行 version 命令时是否自动提交 git commit
"fixed": [], // 强制同步版本的包组（组内任一包更新，全组同步版本）
"linked": [], // 关联版本的包组（版本保持一致，但仅在有变更时更新）
"access": "restricted", // 发布权限：public(公开) 或 restricted(私有)
"baseBranch": "master", // 项目主分支，用于对比变更
"updateInternalDependencies": "patch", // 内部依赖更新时的版本提升策略
"ignore": [] // 忽略版本管理的包
}
🧪 深度解析：updateInternalDependencies
假设我们有两个包，一个依赖另一个：
pkg-a @ version 1.0.0
pkg-b @ version 1.0.0
depends on pkg-a at range `^1.0.0
当我们同时为两者发布 Patch (补丁) 变更（1.0.1）时：
- 设置为
"patch"(默认)：pkg-b对pkg-a的依赖会强制更新为^1.0.1。这是一种积极更新策略，确保内部依赖总是指向最新补丁。 - 设置为
"minor"：pkg-b对pkg-a的依赖将保持^1.0.0。因为变更只是 Patch 级别，未达到 Minor 阈值，所以依赖范围不移动。
4. 规范流程与后续建议
在实际开发中，建议遵循以下“三部曲”：
-
Record (记录变更)： 运行
npx changeset。它会启动交互式菜单：- 选包：按
空格勾选本次有变动的包。 - 定级：选择变更等级。
Major(大变动/不兼容)、Minor(新功能)、Patch(修复 Bug)。 - 写总结：输入简明的变更描述（建议使用中文）。
随后它会在
.changeset/目录下生成一个随机命名的.md文件。这个文件就是你发布前的**“存证”**。
- 选包：按
-
Version (版本提升)： 在准备发布前，运行
npx changeset version。工具会“消费”掉刚才生成的那些.md存证文件，自动更新相关包的package.json版本号，并同步生成/更新CHANGELOG.md。 -
Publish (正式发布)： 运行
pnpm build确保产物最新，然后执行npx changeset publish将你的组件库一键推送到 NPM 仓库。
五、实战演练：发布一个 Patch 补丁版本
在完成文档更新或修复微小 Bug 后，我们需要发布一个 Patch（补丁）版本。以下是本次实战的真实操作记录：
1. 记录变更 (Record)
执行 npx changeset。在交互式菜单中：
- 选包：按
空格勾选@my-antd-ui/components,@my-antd-ui/theme,@my-antd-ui/utils等所有受影响的包。 - 定级：选择
patch。 - 总结：输入
更新发布文档。
2. 提升版本 (Version)
执行 npx changeset version。
- 版本更新：所有相关子包的
package.json版本号从1.0.0统一提升至1.0.1。 - 日志同步：每个包的
CHANGELOG.md都自动插入了本次变更的中文说明。
3. 构建与发布 (Build & Publish)
# 执行 Monorepo 一键构建
pnpm build
# 执行正式发布
npx changeset publish
⚠️ 发布常见错误排查 (Troubleshooting)
1. ENEEDAUTH - 授权失败
现象：error ENEEDAUTH
原因：指向了国内镜像源（如淘宝镜像），或者未在当前终端登录 NPM 账号。
解决：
- 切换官方源：
npm config set registry https://registry.npmjs.org/ - 执行登录：
npm login
2. 402 Payment Required - 作用域权限
现象：发布以 @xxx/ 开头的包时报错。
解决：在发布命令后添加参数，或在 .changeset/config.json 中配置 "access": "public"。
npx changeset publish --access public
3. 403 Forbidden - 2FA 验证失败
现象：error E403 Forbidden - Two-factor authentication... is required
解决：使用 Granular Access Token（勾选 "Bypass 2FA requirement" 选项）并配置到本地 npm。
npm config set //registry.npmjs.org/:_authToken=YOUR_TOKEN_HERE
📦 组件库使用指南
发布成功后，用户可以通过以下方式使用你的组件库：
1. 全局注册
import { createApp } from 'vue'
import MyAntdUI from '@my-antd-ui/components'
import '@my-antd-ui/theme/index.css'
const app = createApp(App)
app.use(MyAntdUI)
app.mount('#app')
2. 按需引入
<script setup lang="ts">
import { MyButton, MyInput, MyMessage } from '@my-antd-ui/components'
import { formatDate } from '@my-antd-ui/utils'
const handleClick = () => {
MyMessage.success('操作成功！')
}
</script>
<template>
<div>
<MyButton type="primary" @click="handleClick">点击我</MyButton>
<MyInput v-model="value" placeholder="请输入内容" />
</div>
</template>
🏁 结语：构建生产级组件库的"四大支柱"
发布组件库不是简单的代码搬运，而是一场关于标准化与自动化的架构实践。
- 统一构建（Standardized Build）：基于 Vite 库模式确保产物跨环境兼容。
- 极智体验（Developer Experience）：通过自动生成
.d.ts与global.d.ts扩展提升开发感。 - 版本契约（Versioning Contract）：引入
Changesets规范迭代流程。 - 质量守卫（Quality Gate）：依托 GitHub Actions 将质量固化。
工程化不是为了解决现在的问题，而是为了预防未来的灾难。 当你学会从“写一个组件”转向“经营一个生态”时，你就已经完成了从普通开发者向系统架构师的跃迁。
相关阅读：
