auto-release

统一的发布工具：支持交互式版本升级、修改日志生成以及 GitHub Release 发布。

auto-release 结合了 bumpp 的交互式体验与 changelogen 强大的修改日志生成和 GitHub Release 功能，为您提供一站式的发布方案。

特性

• 交互式版本管理：支持提示驱动的版本选择（patch, minor, major 等）。
• 约定式提交 (Conventional Commits)：根据 commit 历史自动推断版本号。
• 自动生成修改日志 (Changelog)：自动更新 CHANGELOG.md，并对 commit 进行分类。
• Git 自动化：自动执行 commit、tag 以及 push 操作。
• GitHub Release 同步：将修改日志直接同步到 GitHub Releases。
• NPM 发布：支持自动发布到 NPM 仓库。
• 高度可配置：通过 auto-release.config.ts 定制完整流程。

安装

pnpm add -D @ggcv/auto-release

使用方法

在项目根目录下运行：

pnpm exec auto-release

或者将其添加到 package.json 的 scripts 中：

{
  "scripts": {
    "release": "auto-release"
  }
}

常用命令

基础使用

# 进入交互式界面选择升级类型
pnpm exec auto-release

# 直接升级为特定的语义化版本
pnpm exec auto-release patch
pnpm exec auto-release minor
pnpm exec auto-release major

# 升级到指定版本号
pnpm exec auto-release 1.2.3

自动化流程

# 跳过确认提示 (静默模式)
pnpm exec auto-release -y

# 只升级版本，不自动创建 Git commit 和 Tag
pnpm exec auto-release --no-commit --no-tag

# 全自动化：升级版本 + 生成修改日志 + Git 推送 + 创建 GitHub Release + 发布到 NPM
pnpm exec auto-release --github --publish

特殊场景

# 递归升级 Monorepo 中所有包的版本
pnpm exec auto-release -r

# 发布 Canary 版本 (例如 1.0.0-beta.x)
pnpm exec auto-release --canary

# 升级后执行特定脚本 (例如构建或清理)
pnpm exec auto-release -x "pnpm run build"

修改日志 (Changelog) 控制

# 仅更新修改日志，不升级版本号 (利用 position 参数传递 currentVersion)
pnpm exec auto-release --release none

# 预览最近的 Commit 记录
pnpm exec auto-release --print-commits

配置

在项目中创建 auto-release.config.ts 文件：

import { defineConfig } from "auto-release/config";

export default defineConfig({
  commit: true,
  tag: true,
  push: true,
  github: true,
});

更多详细的定制化玩法（如：修改 Emoji、使用图片图标、映射 Scope 等），请参阅我们的 定制化指南。

高级技巧

临时覆盖包名（发布到私有作用域）

如果您希望在发布到私有仓库时使用特定的作用域前缀（例如 @db/auto-release），但又不想永久修改 package.json 中的 name 字段，可以使用 publish.name 配置。

auto-release 会在执行发布前临时修改 package.json 中的包名，待发布完成后自动还原，确保您的源码和 Git 记录始终保持原始包名。

export default defineConfig({
  publish: {
    // 发布的临时包名
    name: "@xx/auto-release",
    // 配合私有仓库地址使用
    args: ["--registry", "https://your-registry.com"],
  },
});

多包管理器（如 pnpm monorepo）发布与自定义 Registry 支持

auto-release 支持多种主流包管理器环境的无缝发布：

• 自动包管理器侦测：若未在配置中显式指定，工具将首先读取 package.json 中的 packageManager 字段来锁定包管理器类型（例如自动截取自 "[email protected]" 中的 "pnpm"）；若该字段未定义，则自动根据项目根目录的锁文件（如 pnpm-lock.yaml、yarn.lock）识别使用的是 pnpm、yarn、bun 还是 npm。
• pnpm monorepo 兼容：在 pnpm 模式下，工具将使用 pnpm publish 发布。这不仅能够正确解析和转换 package.json 中的 workspace: 依赖协议，而且还会自动在发布命令中补全 --no-git-checks 参数，防止在自动修改版本尚未 commit/push 时引发发布中断。
• 自定义推送镜像源（Registry）：可通过在配置中指定 registry 地址，命令执行时会自动拼接 --registry <registry> 将包发布到特定的私有源或 npm 镜像库。

配置示例：

export default defineConfig({
  publish: {
    // 显式指定包管理器，未指定则系统自动探测
    packageManager: "pnpm",
    // 显式指定推送的 npm 地址
    registry: "https://registry.npmjs.org/",
  },
});

GitHub API Token 配置

如果您在配置中开启了 github: true，auto-release 将尝试调用 GitHub API 自动为您创建关联的 Release 发布。
为了保证接口调用成功，您需要提供 GitHub Token 授权（必填，否则会降级为在浏览器中打开链接手动创建）：

您可以通过以下三种方式中任意一种提供 Token：

1. 配置环境变量 GITHUB_TOKEN （推荐）
2. 配置环境变量 GH_TOKEN
3. 如果您在使用 GitHub CLI (gh) 且已经授权登录过，工具也会尝试自动读取 gh 的授权 Token。

（注意：您的 Token 需要具有 repo 权限以便能正常创建 Release 发版）

许可

基于 MIT 许可协议 © 2026 GGChivalrous