# NPM 包发布指南

本文档介绍如何使用 Changesets 发布 CMTX 项目的 NPM 包。

# 1. 概述

CMTX 项目使用 @changesets/cli 管理版本和发布流程，所有包遵循语义化版本（SemVer）规范。

# 1.1. 版本约束

所有包必须保持 0.x.x 版本系列，第一位（major）严禁 ≥ 1。CMTX 仍处于活跃开发阶段，在以下条件全部满足前不得发布 1.0.0：

所有公开 API 经充分审查并确认稳定
无 fail-open 式静默错误处理
无桩函数（stub）provider 实现
构造函数不执行业务逻辑或抛错
经团队决策同意

违反此约束的版本应立即撤回或标记 deprecated。

# 1.1. 适用范围

适用包列表：

以下包使用本发布流程：

@cmtx/core
@cmtx/storage
@cmtx/template
@cmtx/fpe-wasm
@cmtx/asset
@cmtx/rule-engine
@cmtx/ai
@cmtx/autocorrect-wasm
@cmtx/markdown-it-presigned-url
@cmtx/markdown-it-presigned-url-adapter-nodejs
@cmtx/cli
@cmtx/mcp-server

不适用包：

cmtx-vscode - VS Code 扩展使用 VS Marketplace 的预发布机制（参见 packages/vscode-extension/DEV-006-vscode-publish-guide.md）

# 2. 前置要求

# 2.1. 环境准备

# 确保已安装 Node.js 22+
node --version

# 确保已登录 npm
npm whoami

# 2.2. 权限要求

确保 npm 账号有 @cmtx 组织的发布权限
确认包名在 npm 上可用：https://www.npmjs.com/search?q=@cmtx

# 3. 日常开发流程

# 3.1. 创建变更集

每次功能开发完成后，为更改创建变更集：

pnpm changeset add

按提示操作：

选择受影响的包
选择版本类型（major/minor/patch）
输入更改说明

变更集将保存在 .changeset/ 目录下。

# 3.2. 提交变更集

git add .changeset/*.md
git commit -m "Add changeset for feature X"

# 3.3. 管理 CHANGELOG

CMTX 的 CHANGELOG 由 Changesets 自动生成。每次发布执行 pnpm changeset version 时，Changesets 会整合 .changeset/ 目录下的变更集文件，自动更新各包的 CHANGELOG.md 和版本号。

CHANGELOG 的详细编写规范（包括双语格式要求）参见 DEV-008: Changeset 编写与 CHANGELOG 管理指南。

CHANGELOG 格式示例（先中文后英文）：

# @cmtx/core 更新日志 / Changelog

## [Unreleased]

### Added
- 新功能 A

### Fixed
- 修复 B

## [0.3.0] - 2026-04-03

### Added
- 功能描述

---

### Added
- Feature description

变更类型（参考 Keep a Changelog 分类）：

类型	说明
`Added`	新功能
`Changed`	现有功能变更
`Deprecated`	即将弃用的功能
`Removed`	已移除的功能
`Fixed`	错误修复
`Security`	安全漏洞

# 4. 发布流程

# 4.1. 版本递增与 CHANGELOG 更新

pnpm release:version

该命令执行以下操作：

读取 .changeset/ 下的变更集文件
根据变更类型（major/minor/patch）递增各包的版本号
自动更新各包的 CHANGELOG.md
清理已使用的变更集文件

# 4.2. 发布到 NPM

pnpm release:publish

该命令执行以下操作：

构建所有包
验证构建产物
将各包发布到 NPM
创建并推送 Git tags

# 4.3. 一键执行（版本递增 + 发布）

pnpm release:all

该命令依次执行 release:version 和 release:publish。适用于确认无冲突的常规发布场景。

# 4.4. 提交

发布完成后提交版本变更：

git add -A && git commit -m "Release v<version>"

# 5. 发布前验证清单

发布前必须检查：

[ ] TypeDoc 注释覆盖检查 (pnpm run docs:check 无报错)
[ ] 所有包构建成功 (pnpm -r build)
[ ] 所有测试通过 (pnpm -r test)
[ ] TypeScript 类型检查通过 (pnpm -r typecheck)
[ ] 代码格式检查通过 (pnpm lint)
[ ] dist 文件存在：build 后 dist/index.js 和 dist/index.d.ts
[ ] CHANGELOG 完整：包含 [Unreleased] 章节和版本记录，采用先中文后英文的双语格式
[ ] README 准确：版本正确，功能说明完整
[ ] 已登录 npm (npm whoami)
[ ] 当前分支为 main 分支
[ ] 工作区干净，无未提交更改

# 6. 验证包内容

# 6.1. 安装测试

安装正式版：

npm install @cmtx/cli

安装特定版本：

npm install @cmtx/cli@<version>

# 6.2. 检查类型定义

# 在临时目录安装并测试
mkdir /tmp/test-cmtx
cd /tmp/test-cmtx
npm install @cmtx/core@<version>

# 检查类型定义
head -20 node_modules/@cmtx/core/dist/index.d.ts

# 验证导出
node -e "import('@cmtx/core').then(m => console.log(Object.keys(m)))"

# 7. 本地测试

# 7.1. Dry-run 预览

pnpm changeset publish --dry-run

# 7.2. Verdaccio 本地测试（未来可选）

待项目稳定后，可使用 Verdaccio 进行更完整的发布测试：

# 安装 verdaccio
pnpm add -g verdaccio

# 启动本地 npm 仓库
verdaccio

# 配置 npm 指向本地仓库
npm set registry http://localhost:4873

# 发布到本地仓库
pnpm changeset publish --no-git-tag

# 测试安装
npm install @cmtx/cli@<version>

# 恢复默认 registry
npm set registry https://registry.npmjs.org

# 8. 故障排除

# 8.1. 发布失败

如果发布中途失败：

检查错误日志
修复问题后重新运行发布命令
Changesets 会跳过已发布的版本

# 8.2. 版本号冲突

确保没有其他人在同时发布，如有冲突：

拉取最新代码：git pull
重新运行 version 命令
重新发布

# 8.3. Git tag 推送失败

# 手动推送 tags
git push --follow-tags

# 8.4. 如何撤销发布？

在 24 小时内可撤销：

npm unpublish @cmtx/core@<version>

之后需要联系 npm support。

# 8.5. 发布失败常见原因

未登录或无权限：npm login 重新登录
版本已存在：升级 package.json 中的版本号
网络问题：检查网络连接，重试

# 9. 参考文档

最后更新: 2026-07-31 19:58:33 +0800 在 GitHub 上编辑此页