release-it

Release It! 🚀

🚀 用于自动执行版本管理和软件包发布相关任务的通用 CLI 工具：

• 更新版本（例如 package.json 中的版本）
• 执行 Git 提交、打标签并推送
• 使用 钩子 执行任意（测试或构建）命令
• 在 GitHub 或 GitLab 创建发布
• 生成更新日志
• 发布到 npm
• 管理预发布版本
• 使用 插件 扩展
• 从任意 CI/CD 环境发布

使用 release-it 管理版本，并通过灵活的配置、强大的插件系统和钩子，在任何地方发布。钩子可执行你需要的任意命令，用于测试、构建和/或发布项目。

你在工作中使用 release-it 吗？欢迎考虑赞助我！

安装

虽然 release-it 是一款通用发布工具，但大多数项目会将它用于包含 npm 软件包的项目。推荐通过 npm 安装 release-it，并添加一些最精简的配置以便开始使用：

npm init release-it

你也可以手动安装，并将 release 脚本添加到 package.json：

npm install -D release-it

{
  "name": "my-package",
  "version": "1.0.0",
  "scripts": {
    "release": "release-it"
  },
  "devDependencies": {
    "release-it": "^21.0.0"
  }
}

使用方法

在项目根目录下使用 npm run 或 npx 运行 release-it：

npm run release
npx release-it

系统会提示你选择新版本，并根据你的配置显示后续提示。

Yarn 和 pnpm

• 使用 Yarn？请参阅 Yarn 的 npm 部分。
• 使用 pnpm？请参阅 release-it-pnpm。

Monorepo

使用 Monorepo？请参阅这份 Monorepo 配方。

全局安装

推荐像上文所示那样按项目安装，但也支持全局安装：

• 从 npm 安装：npm install -g release-it
• 从 Homebrew 安装：brew install release-it

容器化

使用 Release It! - Containerized，即可在任何环境中将其作为标准化容器运行，无需 Node 环境。感谢 Juan Carlos！

视频、文章和示例

以下是一些有趣的外部资源：

• 视频：如何使用 GitHub Actions 和 Release-It 轻松发布代码
• 文章：Monorepo 语义化发布（仓库）

想将你的内容添加到列表中？只需提交一个拉取请求！

配置

release-it 开箱即用，具有合理的默认值，并提供丰富的选项供你配置。大多数项目会在项目根目录中使用 .release-it.json 文件，或在 package.json 中使用 release-it 属性。

以下是一个简短的 .release-it.json 示例：

{
  "$schema": "https://unpkg.com/release-it@20/schema/release-it.json",
  "git": {
    "commitMessage": "chore: release v${version}"
  },
  "github": {
    "release": true
  }
}

→ 详情请参阅配置。

交互模式与 CI 模式

默认情况下，release-it 采用交互模式，允许你在执行每项任务前进行确认：

使用 --ci 选项后，整个流程会自动运行，不再显示提示。系统将执行已配置的任务，如上方第一个动画所示。在持续集成（CI）环境中，此非交互模式会自动启用。

使用 --only-version 仅通过提示来确定版本，并自动执行其余操作。

最新版本

release-it 如何确定最新版本？

1. 对于包含 package.json 的项目，将使用其中的 version（如需跳过此项，请参阅 npm）。
2. 否则，release-it 会使用最新的 Git 标签来确定要发布的版本。
3. 如果以上方法都不可用，则会使用 0.0.0 作为最新版本。

你也可以使用插件来覆盖此行为（例如，管理 VERSION 或 composer.json 文件）：

• 使用 @release-it/bumper 从任意文件中读取或更新版本
• 使用 @release-it/conventional-changelog 根据提交消息获取建议的版本更新级别
• 使用 release-it-calver-plugin 采用 CalVer（Calendar Versioning，日历版本控制）

添加 --release-version 标志，即可输出下一个版本，而不执行发布。如果没有可用的下一个版本，则不会输出任何内容，并会成功退出。

Git

release-it 对 Git 项目的支持完善，可自动完成暂存、提交、打标签并将发行版本推送到任意 Git 远程仓库。

→ 更多详情请参阅 Git。

npmjs.com 发行

截至 2025 年 7 月，GitHub 和 GitLab CI 工作流现在可以使用 npm 的 Trusted Publishing OpenID Connect（OIDC）集成，实现安全的无令牌 CI/CD 发布。这可以消除长期有效的令牌，并自动生成来源证明。详情请参阅 docs/npm.md。

GitHub 发行

GitHub 项目可以将发行版本关联到 Git 标签，并附上发行说明和资源。在 release-it 工作流中添加 GitHub 发行有两种方式：

1. 自动化（需要 GITHUB_TOKEN）
2. 手动（使用预填充字段的 GitHub 网页界面）

→ 更多详情请参阅 GitHub Releases。

GitLab 发行

GitLab 项目可以将发行版本关联到 Git 标签，并附上发行说明和资源。若要自动化 GitLab 发行：

• 配置 gitlab.release: true
• 获取个人访问令牌（release-it 需要 api 和 self_rotate 范围）。
• 确保令牌可作为环境变量使用。

→ 更多详情请参阅 GitLab Releases。

更新日志

默认情况下，release-it 会生成更新日志，用于显示并帮助选择新发行版本的版本号。此外，此更新日志还会作为 GitHub 或 GitLab 发行版本的发行说明。

默认命令基于 git log ...。此设置（git.changelog）可以覆盖。若要进一步自定义 GitHub 或 GitLab 发行版本的发行说明，可以使用 github.releaseNotes 或 gitlab.releaseNotes。请确保这些命令中的任意一个都将更新日志输出到 stdout。请注意，release-it 默认不限定提交消息规范。以下插件可供使用：

• GitHub 和 GitLab 发行
• auto-changelog
• Conventional Changelog
• Keep A Changelog
• git-cliff

若要在不发行任何内容的情况下打印更新日志，请添加 --changelog 标志。

→ 更多详情请参阅 Changelog。

发布到 npm

如果当前目录中有 package.json，release-it 会让 npm 更新 package.json 中的版本（如果存在，也会更新 package-lock.json），并发布到 npm 注册表。

→ 更多详情请参阅 Publish to npm。

管理预发行版本

使用 release-it 可以轻松创建预发行版本：这是一种尚未进入稳定 semver 范围、但希望提前提供给用户的软件版本。预发行版本通常使用“alpha”、“beta”和“rc”（发行候选版）作为标识符。预发行版本示例：2.0.0-beta.0。

→ 更多详情请参阅 Manage pre-releases。

更新或重新运行现有发行版本

使用 --no-increment 不增加版本号，而是更新最后一个现有标签/版本。

如果版本号已经增加过，这会很有帮助。以下是一些示例场景：

• 为现有 Git 标签更新或发布（草稿）GitHub 发行版本。
• 发布到 npm 已成功，但将 Git 标签推送到远程仓库失败。此时使用 release-it --no-increment --no-npm 跳过 npm publish，并再次尝试推送同一个 Git 标签。

Hooks

使用脚本钩子，在发布流程的任意时刻运行 shell 命令（例如 before:init 或 after:release）。

格式为 [prefix]:[hook] 或 [prefix]:[plugin]:[hook]：

部分	值
prefix	before 或 after
plugin	version、git、npm、github、gitlab
hook	init、bump、release

使用中间可选的 :plugin 部分，可在任何插件的生命周期方法之前或之后准确地挂接钩子。

核心插件包括 version、git、npm、github、gitlab。

请注意，如果 git push 失败，或者配置为不执行（例如 git.push: false），则 after:git:release 之类的钩子不会运行。有关插件生命周期方法执行顺序的更多信息，请参阅执行顺序。

使用 --no-hooks 跳过所有钩子，或从命令行禁用单个钩子（例如 --no-hooks.before:init）。

所有命令都可以使用配置变量（例如模板字符串）。也可以提供命令数组，它们会依次运行。以下是一些 release-it 配置示例：

{
  "hooks": {
    "before:init": ["npm run lint", "npm test"],
    "after:my-plugin:bump": "./bin/my-script.sh",
    "after:bump": "npm run build",
    "after:git:release": "echo After git push, before github release",
    "after:release": "echo Successfully released ${name} v${version} to ${repo.repository}."
  }
}

变量可在默认配置中找到。此外，还提供了以下变量：

version
latestVersion
changelog
name
repo.remote, repo.protocol, repo.host, repo.owner, repo.repository, repo.project
branchName
releaseUrl

所有钩子都可以使用所有变量。唯一的例外是，上面列出的附加变量在 init 钩子中尚不可用。

使用 --verbose 记录命令的输出。

为完整起见，钩子的完整列表实际上是：init、beforeBump、bump、beforeRelease、release 或 afterRelease。不过，像 before:beforeRelease 这样的钩子看起来很奇怪，实际使用中通常也没有用。

请注意，从命令行使用时，参数需要正确加引号：

release-it --'hooks.after:release="echo Successfully released ${name} v${version} to ${repo.repository}."'

在自定义钩子脚本中使用 @inquirer/prompts 可能会导致问题（因为 release-it 本身也会使用它）。

Dry Runs

使用 --dry-run 查看交互过程以及将要执行的命令。

→ 更多详情请参阅 Dry Runs。

故障排除与调试

• 使用 release-it --verbose（或 -V）时，release-it 会打印每个用户定义的钩子的输出。
• 使用 release-it -VV 时，release-it 还会打印每条内部命令的输出。
• 使用 NODE_DEBUG=release-it:* release-it [...] 打印配置和更多错误详情。

在配置文件中使用 verbose: 2，即可获得与在命令行中使用 -VV 相同的效果。

插件

从 v11 开始，release-it 可以通过许多方式扩展。以下是一些插件：

插件	描述
@release-it/bumper	从任意文件读取版本并将版本写入任意文件
@release-it/conventional-changelog	提供推荐的版本升级、conventional-changelog，并更新 CHANGELOG.md
@release-it/keep-a-changelog	按照 Keep a Changelog 标准维护 CHANGELOG.md
@release-it-plugins/lerna-changelog	将 lerna-changelog 集成到 release-it 发布流程中
@jcamp-code/release-it-changelogen	使用 @unjs/changelogen 进行版本管理和生成变更日志
@release-it-plugins/workspaces	发布配置为工作区的每个项目
release-it-calver-plugin	通过 release-it 启用日历版本控制（calver）
@grupoboticario/news-fragments	一种轻松生成变更日志文件的方式
@j-ulrich/release-it-regex-bumper	基于正则表达式的 release-it 版本读取/写入插件
@jcamp-code/release-it-dotnet	使用 .csproj 或 .props 文件进行版本管理，自动发布 NuGet
release-it-pnpm	添加 pnpm 工作区的基本支持，并与 bumpp 和 changelogithub 集成
changesets-release-it-plugin	将 Changesets 变更日志管理与 release-it 结合
release-it-gitea	Gitea 插件，用于创建 Gitea 发布并上传附件
release-it-beautiful-changelog	使用 conventional commits 通过 @unjs/changelogen 生成美观的变更日志
release-it-git-cliff	使用 git-cliff 确定下一个版本并生成变更日志

在内部，release-it 使用自己的插件架构（用于 Git、GitHub、GitLab、npm）。

→ 查看 npm 上的所有 release-it 插件。

→ 查看 插件 文档，了解如何编写插件。

以编程方式使用 release-it

release-it 主要作为命令行工具使用，也可以作为依赖项集成到你自己的脚本中。请参阅以编程方式使用 release-it，查看示例代码。

使用 release-it 的项目

• AdonisJs
• Axios
• Chakra UI
• Halo
• hosts
• js-cookie
• jQuery
• Madge
• Metalsmith
• n8n
• Node-Redis
• React Native Paper
• Readability.js
• Redux
• Saleor
• Semantic UI React
• tabler-icons
• Swagger（swagger-ui + swagger-editor）
• 依赖 release-it 的仓库
• GitHub 上搜索 path:**/.release-it.json

Node.js 版本支持

最新的主版本是 v21，支持 Node.js 22.21 及更高版本：

release-it	Node.js
v21	v22.21.0
v20	v20.19.0
v19	v20.12.0
v18	v20
v17	v18
v16	v16
v15	v14

日期和详情另请参阅 CHANGELOG.md。

链接

• 有关重大更新和破坏性变更，请参阅 CHANGELOG.md；详细的版本历史请参阅发布记录。
• 如需贡献，请先阅读 CONTRIBUTING.md。
• 如果本文档中有任何缺失或不清楚之处，请提交问题。

许可证

MIT

在工作中使用 release-it？欢迎考虑赞助我！