@vyron/release

@vyron/release

一站式发布流水线，支持 Git、NPM、GitHub Release 自动化管理

特性

• 交互式发布 - 友好的命令行交互，选择版本类型和 commit message
• 多包支持 - 支持 monorepo 一次性发布多个包
• 版本校验 - 自动检查 npm 是否已有该版本，避免重复发布
• CHANGELOG - 自动生成/更新 CHANGELOG.md
• GitHub Release - 自动创建 GitHub Release 和 Release Notes
• 发布确认 - 发布前二次确认，避免误操作
• 自动回滚 - 发布失败时自动回滚版本号
• 进度反馈 - 所有操作都有清晰的进度和结果提示
• 错误重试 - 网络操作失败自动重试（最多 3 次）
• Dry Run - 预览模式，不实际执行任何操作

Install

pnpm add @vyron/release

Quick Start

import { release } from "@vyron/release";

// 交互式发布
await release();

// 指定版本类型
await release({ patch: true });
await release({ minor: true });
await release({ major: true });

// 指定自定义版本
await release({ custom: "2.0.0" });

// 预览模式
await release({ dryRun: true });

CLI Usage

# 交互式发布
pnpm release

# 指定版本类型
pnpm release --minor
pnpm release --patch
pnpm release --major

# 指定自定义版本
pnpm release --custom 2.0.0

# 预发布版本
pnpm release --minor --pre-release alpha
pnpm release --patch --pre-release beta
pnpm release --major --pre-release rc

# 预览模式
pnpm release --dry-run

# 跳过确认
pnpm release --skip-confirm

# 发布后跳过 GitHub Release
pnpm release --skip-github-release

# 发布后跳过 CHANGELOG
pnpm release --skip-changelog

# 跳过 Git Push
pnpm release --skip-push

# 跳过 NPM Publish
pnpm release --skip-publish

API

release(options?)

发布新版本。

import { release } from "@vyron/release";

// 交互式发布
await release();

// 指定版本类型
await release({ minor: true });
await release({ patch: true });
await release({ major: true });

// 指定自定义版本
await release({ custom: "2.0.0" });

// 预发布版本
await release({ minor: true, preRelease: "alpha" });
await release({ patch: true, preRelease: "beta" });
await release({ major: true, preRelease: "rc" });

// 完整选项
await release({
  // 工作目录，默认 process.cwd()
  cwd: process.cwd(),

  // 预览模式，不实际发布
  dryRun: false,

  // 版本类型（与 CLI 一致）
  patch: false,
  minor: false,
  major: false,
  custom: undefined, // 或指定版本号如 "2.0.0"
  preRelease: undefined, // "alpha" | "beta" | "rc"

  // 自定义 commit message
  commitMessage: "feat: add new feature",

  // 跳过各步骤
  skipPublish: false,
  skipPush: false,
  skipConfirm: false,
  skipChangelog: false,
  skipGithubRelease: false,

  // 发布单个包（路径）
  package: "./packages/my-package",

  // 配置文件（见下文）
  config: {
    parallel: false,
    changelog: { output: "CHANGELOG.md" },
    githubRelease: { draft: false },
  },
});

Options

Option	Type	Default	Description
cwd	string	process.cwd()	工作目录
dryRun	boolean	false	预览模式，不实际执行
patch	boolean	false	发布 patch 版本
minor	boolean	false	发布 minor 版本
major	boolean	false	发布 major 版本
custom	string	undefined	指定自定义版本号
preRelease	string	undefined	预发布标识 (alpha/beta/rc)
commitMessage	string	自动生成	Git commit message
skipPublish	boolean	false	跳过 NPM 发布
skipPush	boolean	false	跳过 Git Push
skipConfirm	boolean	false	跳过发布确认
skipChangelog	boolean	false	跳过 CHANGELOG 更新
skipGithubRelease	boolean	false	跳过 GitHub Release
package	string	自动选择	指定发布的包路径
config	object	-	配置文件

Configuration

在项目根目录创建 .releaserc.json 或 release.config.js：

.releaserc.json

{
  "parallel": false,
  "changelog": {
    "output": "CHANGELOG.md"
  },
  "githubRelease": {
    "draft": false,
    "prerelease": false
  }
}

release.config.js

export default {
  parallel: false,
  changelog: {
    output: "CHANGELOG.md",
  },
  githubRelease: {
    draft: false,
    prerelease: false,
  },
};

Config Options

Key	Type	Description
parallel	boolean	多包发布时并行执行
changelog.output	string	CHANGELOG 文件路径
githubRelease.draft	boolean	创建为 Draft Release
githubRelease.prerelease	boolean	创建为 Pre-release

Programmatic API

release(options?)

主入口函数，详见上文。

readPkg(cwd?)

读取 package.json 信息。

import { readPkg } from "@vyron/release";

const pkg = readPkg("./packages/my-package");
// pkg.name    - 包名
// pkg.version - 版本号
// pkg.path    - package.json 路径

writePkg(cwd, version)

更新 package.json 版本号。

import { writePkg } from "@vyron/release";

writePkg("./packages/my-package", "2.0.0");

calculateNewVersion(currentVersion, releaseType)

计算新版本号。

import { calculateNewVersion } from "@vyron/release";

calculateNewVersion("1.0.0", "patch"); // "1.0.1"
calculateNewVersion("1.0.0", "minor"); // "1.1.0"
calculateNewVersion("1.0.0", "major"); // "2.0.0"
calculateNewVersion("1.0.0", "2.0.0"); // "2.0.0"

isValidVersion(version)

验证版本号是否合法。

import { isValidVersion } from "@vyron/release";

isValidVersion("1.0.0"); // true
isValidVersion("1.0.0-beta"); // true
isValidVersion("invalid"); // false

Workflow

发布流程：

flowchart TD
    A[开始] --> B{Git 状态检查}
    B -->|未初始化| C[初始化 Git 仓库]
    B -->|有未提交更改| D[提交或暂存更改]
    B -->|无 remote| E[设置 remote]
    C --> F
    D --> F
    E --> F

    F{单包或多包模式?} -->|单包| G[读取当前包信息]
    F -->|多包| H[选择要发布的包]

    H --> I[循环处理每个包]
    G --> I

    I --> J[选择版本类型]
    J -->|Patch| K["版本升级: 1.0.0 → 1.0.1"]
    J -->|Minor| L["版本升级: 1.0.0 → 1.1.0"]
    J -->|Major| M["版本升级: 1.0.0 → 2.0.0"]
    J -->|Custom| N[输入自定义版本]
    J -->|Cancel| Z[取消发布]

    K --> O{npm 已存在该版本?}
    L --> O
    M --> O
    N --> O

    O -->|是| P[错误: 版本已存在]
    O -->|否| Q[更新 package.json]

    P --> Z
    Q --> R{确认发布?}

    R -->|否| Z
    R -->|是| S[更新 CHANGELOG]

    S --> T[创建 GitHub Release]
    T --> U[Git Commit & Tag]
    U --> V[Git Push]
    V --> W[NPM Publish]
    W --> X[成功]

    X --> Y{"还有更多包?"}
    Y -->|是| I
    Y -->|否| AA[🎉 全部完成]

    style Z fill:#ff6b6b,color:#fff
    style P fill:#ff6b6b,color:#fff
    style X fill:#51cf66,color:#fff
    style AA fill:#51cf66,color:#fff

流程说明

步骤	说明	可跳过
Git 状态检查	检查仓库状态，提示初始化/提交/设置 remote	否
选择包	多包模式下选择要发布的包	单包模式自动跳过
版本选择	选择 patch/minor/major 或自定义版本	可指定 patch/minor/major/custom
版本检查	验证 npm 是否已有该版本	否
发布确认	二次确认是否发布	--skip-confirm
CHANGELOG	自动更新 CHANGELOG.md	--skip-changelog
GitHub Release	创建 GitHub Release 和 Release Notes	--skip-github-release
Git Commit	提交更改并打标签	否
Git Push	推送到远程仓库	--skip-push
NPM Publish	发布到 npm	--skip-publish

Error Handling

发布过程中遇到错误会自动回滚版本号更改。

常见错误提示：

错误	原因	解决方案
未找到 package.json	工作目录不正确	使用 cwd 选项指定正确路径
版本 x.x.x 已存在于 npm	该版本已发布	使用新的版本号
npm publish 失败	未登录 npm	运行 npm login
git push 失败	网络问题或无权限	检查网络或 Git 配置
版本格式不正确	包名不符合规范	确保符合 npm 包名规范

Environment Variables

Variable	Description
GITHUB_TOKEN	GitHub API Token，用于创建 Release
npm_token	npm 认证 Token

Best Practices

• 使用 Dry Run 测试 - 首次使用时先用 --dry-run 预览效果

• 配置文件管理 - 在项目中添加 .releaserc.json 统一团队配置

• 版本号规范 - 遵循 semver 规范：

  • patch - Bug 修复
  • minor - 新功能（向后兼容）
  • major - 破坏性变更

• Commit Message - 使用有意义的 commit message，便于生成 changelog

• GITHUB_TOKEN - 创建 GitHub Release 需要设置环境变量

License

MIT