发布方法

本文档面向项目维护者，介绍如何发布 xiaozhi-client 项目到 npm。

发布权限要求: 你需要拥有项目仓库的维护权限，并且配置了正确的 NPM_TOKEN 密钥。

版本号规范

项目采用语义化版本号（Semantic Versioning），支持以下版本类型：

版本类型	格式示例	说明
正式版	`1.0.0`	稳定的生产版本
Beta版	`1.0.0-beta.0`	测试版本，可能包含未完成的功能
RC版	`1.0.0-rc.0`	候选发布版本，接近正式版

版本号规则:

正式版必须在 main 分支发布
Beta/RC 版本可以在任意分支发布测试
所有包使用统一版本号

发布的包

项目采用多包发布策略，每次发布会同时发布以下包：

xiaozhi-client - 主包，CLI 工具
@xiaozhi-client/cli - CLI 核心库
@xiaozhi-client/config - 配置管理库
@xiaozhi-client/shared-types - 共享类型定义

所有包使用相同的版本号，由 nx release 自动管理。

发布步骤

准备工作

确保当前代码已通过所有测试
检查 CHANGELOG.md 或 docs/changelog.mdx 是否需要更新
确认要发布的版本号

本地准备发布


# 标准发布
pnpm release 1.10.7
 
# Beta 版本
pnpm release 1.10.8-beta.0
 
# RC 版本
pnpm release 1.10.8-rc.0

此命令会：

✅ 验证版本号格式
✅ 检查工作目录状态
✅ 更新所有包的版本号
✅ 生成/更新 CHANGELOG.md
✅ 创建 Git commit
✅ 创建 Git tag（如 v1.10.7）
✅ 推送代码和 tag 到远程仓库

推送到远端

新的发布命令已自动包含推送步骤，无需手动推送。

如果使用 --skip-push 参数，则只更新版本号，不推送：


# 仅更新版本号，不推送
pnpm release 1.10.7 --skip-push
 
# 稍后手动推送
git push origin main
git push origin --tags

自动发布

推送 tag 后，GitHub Actions 会自动：

检测到新的 version tag
构建所有包
发布到 npm
创建 GitHub Release

验证发布结果

发布完成后，验证以下内容：

检查 GitHub Actions 执行状态
在 npm 确认包版本
检查 GitHub Releases 是否创建

预演模式

预演模式（Dry Run）: 预演模式会模拟发布流程，查看将要发布的版本信息，但不会实际修改任何文件。


# 预演模式：查看将要发布的版本（不实际修改）
pnpm release 1.10.9-beta.0 --dry-run

本地测试

在正式发布前，你可以在本地进行测试：

测试发布流程


# 预演模式
pnpm release 1.10.9-beta.0 --dry-run
 
# 准备发布（不推送）
pnpm release 1.10.9-beta.0 --skip-push
 
# 检查生成的 commit 和 tag
git log --oneline -3
git tag -l

测试本地构建


# 构建所有包
pnpm run build
 
# 检查构建产物
ls -la dist/

回滚处理

如果发布发现问题，可以执行以下回滚操作：

npm 包回滚


# 标记包为已废弃
npm deprecate xiaozhi-client@VERSION "This version has issues"
npm deprecate @xiaozhi-client/cli@VERSION "This version has issues"
npm deprecate @xiaozhi-client/config@VERSION "This version has issues"
npm deprecate @xiaozhi-client/shared-types@VERSION "This version has issues"

Git 标签回滚


# 删除本地标签
git tag -d vVERSION
 
# 删除远程标签
git push origin :refs/tags/vVERSION

恢复版本号


# 恢复 package.json 版本到上一个提交
git checkout HEAD~1 -- package.json packages/*/package.json
 
# 或者使用 nx release 重新指定正确的版本
nx release version --version 1.9.4

常见问题

⚠️

正式版必须在 main 分支发布 如果你尝试在其他分支发布正式版，工作流会报错。请先合并到 main 分支再发布。

⚠️

版本号格式必须正确 版本号必须符合语义化版本规范：主版本.次版本.修订版本（如 1.0.0）预发布版本格式：主版本.次版本.修订版本-预发布标识.预发布版本（如 1.0.0-beta.0）

ℹ️

版本同步 nx release 会自动同步所有包的版本号，所有包将使用相同的版本号（固定版本模式）。

手动触发发布（备用）

除标准流程外，也支持手动触发 GitHub Actions：

进入项目的 GitHub Actions 页面
选择 NPM 发布 工作流
点击 Run workflow
选择预演模式（可选）

推荐使用标准流程 标准流程（本地命令 + 自动发布）更符合 Nx 最佳实践，可以预览版本变更后再推送。