# release-cli

**Repository Path**: vitarx/release-cli

## Basic Information

- **Project Name**: release-cli
- **Description**: A CLI tool for automated npm package release with workspace support
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-10
- **Last Updated**: 2025-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @vitarx/release-cli

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

## 功能特性

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

## 安装

### 全局安装

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

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

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

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

### 临时使用 (无需安装)

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

```bash
# 使用 npx
npx @vitarx/release-cli

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

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

## 使用方法

### 基本使用

```bash
# 发布当前包 (自动检测包管理器)
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
```

### 高级用法

```bash
# 组合使用选项
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` 选项直接指定要发布的包名或目录名，避免交互式选择：

```bash
# 按包名指定
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](https://www.conventionalcommits.org/) 规范。
2. 如果是多包项目，请确保 根`package.json` 中包含 `name` 字段，如果发布的包名同根包名，则生成根目录的 changelog。

## 开发

### 安装依赖

```bash
pnpm install
```

### 构建项目

```bash
pnpm run build
```

### 本地测试

```bash
# 使用 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