@vitarx/release-cli

一个用于自动化发布 npm 包的 CLI 工具，支持 workspace 模式和多种包管理器。

功能特性

• ✅ 自动化版本管理和发布
• ✅ 支持 npm、pnpm、yarn 包管理器检测
• ✅ 支持 workspace 多包项目管理
• ✅ 支持指定包名发布 (--package 选项)
• ✅ 交互式版本类型选择
• ✅ 预发布版本支持（alpha、beta、rc）
• ✅ 自动生成 changelog (workspace多包项目时仅在发布的包名同根包名时在根目录生成 changelog)
• ✅ dry-run 模式测试
• ✅ 错误回滚机制

安装

全局安装

安装时使用包名 @vitarx/release-cli，安装后使用命令名 release-cli：

# 使用 npm
npm install -g @vitarx/release-cli

# 使用 pnpm  
pnpm install -g @vitarx/release-cli

# 使用 yarn
yarn global add @vitarx/release-cli

临时使用 (无需安装)

临时使用时使用包名 @vitarx/release-cli：

# 使用 npx
npx @vitarx/release-cli

# 使用 pnpm
pnpm dlx @vitarx/release-cli

# 使用 yarn
yarn dlx @vitarx/release-cli

使用方法

基本使用

# 发布当前包 (自动检测包管理器)
release-cli # 如果是 workspace 项目，会以对话形式选择要发布的包

# 指定包名发布 (workspace 项目)
release-cli --package my-package #发布包名为my-package的包
release-cli --package packages/my-package #发布在packages/my-package下的包

# 使用 dry-run 模式测试
release-cli --dry-run

# 指定版本类型
release-cli patch
release-cli minor
release-cli major
# 自定义版本号
release-cli 1.0.1

高级用法

# 组合使用选项
release-cli patch --dry-run --package my-package
release-cli minor --verbose

# 预发布版本
release-cli prerelease --preid alpha
release-cli prerelease --preid beta
release-cli prerelease --preid rc

# 从预发布升级到正式版本
release-cli release

# changelog 相关选项
release-cli patch --preset conventionalcommits --infile HISTORY.md
release-cli minor --no-same-file --output-unreleased
release-cli major --tag-prefix "v" --release-count 5

支持的版本类型

• patch - 修复 bug 或兼容性更新
• minor - 新增功能（兼容旧版本）
• major - 重大变更（不兼容旧版本）
• prepatch - 预发布补丁版本
• preminor - 预发布功能版本
• premajor - 预发布主版本
• prerelease - 预发布版本（递增 preid）
• release - 从预发布版本升级为正式版本
• custom - 自定义版本号

命令行选项参考

| 选项 | 缩写 | 描述 | 默认值 | |-----------------------|------|--------------------------|----------------| | --version | -v | 显示版本信息 | - | | --help | -h | 显示帮助信息 | - | | --dry-run | -d | 试运行模式，不实际执行操作 | false | | --preid | - | 预发布版本标识符（alpha/beta/rc） | - | | --preset | - | conventional-changelog预设 | angular | | --infile | - | changelog输入文件名 | CHANGELOG.md | | --outfile | -o | changelog输出文件名 | 同输入文件 | | --same-file | -s | 追加到现有changelog文件 | true | | --no-same-file | - | 禁用追加到现有changelog文件 | - | | --append | -a | 将新版本追加到旧版本后面 | - | | --first-release | -f | 首次生成changelog | - | | --skip-unstable | - | 跳过不稳定版本（alpha/beta/rc） | - | | --output-unreleased | -u | 输出未发布的变更日志 | - | | --config | -n | 自定义配置文件路径 | - | | --context | -c | 模板变量上下文文件 | - | | --commit-path | - | 只生成指定目录的提交日志 | - | | --tag-prefix | - | Git 标签前缀 | v | | --verbose | - | 详细输出模式 | false | | --release-count | - | 生成的发布记录数量 | 0 | | --package | - | 指定要发布的包名/包相对路径 | - |

Workspace 支持

如果你的项目是 workspace 项目（包含 workspaces 配置），工具会自动检测并让你选择要发布的包。

你可以使用 --package 选项直接指定要发布的包名或目录名，避免交互式选择：

# 按包名指定
release-cli --package my-package
release-cli patch --package my-package --dry-run

# 按目录名指定（workspace项目）
release-cli --package lib
release-cli --package app

发布流程

1. Git 状态检查 - 确保工作目录干净
2. 版本类型选择 - 交互式选择版本升级类型
3. 版本号更新 - 自动更新 package.json 版本号
4. 构建项目 - 执行构建命令（如果存在）
5. Changelog 生成 - 如果是主包发布则使用 conventional-changelog 生成变更日志
6. Git 提交 - 提交版本变更和 changelog
7. NPM 发布 - 发布到 npm 仓库
8. Git 标签 - 创建版本标签
9. Git 推送 - 推送代码和标签到远程仓库

从第2个步骤过后发生异常，都会回滚所有更改。

配置要求

项目配置

确保你的项目包含：

• package.json - 包含正确的包信息
• 构建脚本 - 在 package.json 的 scripts.build 中定义
• Git 仓库 - 已初始化并配置远程仓库
• 多包项目 - 在 package.json 中指定 workspaces和name（用于生成 changelog）

Conventional Changelog

1. 工具使用 conventional-changelog-cli 生成 changelog，确保你的提交信息符合 Conventional Commits 规范。
2. 如果是多包项目，请确保 根package.json 中包含 name 字段，如果发布的包名同根包名，则生成根目录的 changelog。

开发

安装依赖

pnpm install

构建项目

pnpm run build

本地测试

# 使用 dry-run 模式测试
node dist/index.js --dry-run

# 测试特定版本类型
node dist/index.js patch --dry-run

# 测试指定包名发布
node dist/index.js patch --dry-run --package test-package

许可证

MIT License