中文 | English
Varlet Release 是一个用于发布所有包、生成变更日志和检测 commit message 的辅助工具，依赖于 pnpm。
- 📦 开箱即用：零配置的极简发布体验
- 🤖 直观交互：提供非常友好的交互式终端提示
- 🛠 规范驱动：自动校验 Git Commit 并生成标准 Changelog
- 🔗 深度扩展：支持命令行调用与 Node.js API 无缝扩展
Varlet Release需要Node.js^20.19.0 || >=22.12.0，并且仅支持esm。
从 v1 升级到 v2 时，请先阅读 迁移指南。
安装依赖：
pnpm add @varlet/release simple-git-hooks -D在 package.json 中添加以下配置：
{
"scripts": {
"prepare": "simple-git-hooks",
"release": "vr release",
"changelog": "vr changelog"
},
"simple-git-hooks": {
"commit-msg": "pnpm exec vr commit-lint $1",
"post-merge": "pnpm exec vr lockfile-check --install"
}
}现在你可以：
- 按照 Conventional Commits 规范编写提交信息，
commit-lint会自动校验。 - 拉取或合并代码后，
lockfile-check会自动检测 lockfile 变化（pnpm-lock.yaml、yarn.lock、package-lock.json）并重新安装依赖。 - 运行
pnpm release启动交互式发布流程。
- release - 自动完成从版本号变更到发布、打标签的标准工作流。
- publish - 单独执行 npm 发布流程，通常适用于 CI/CD 环境。
- changelog - 根据 Git Commit 规范自动生成格式化的变更日志。
- commit-lint - 校验 Git Commit Message 是否符合规范，帮助团队统一提交格式。
- lockfile-check - 检查项目 lockfile 状态并在变化时提供更新依赖机制。
作用：包版本发布的核心功能集合，集成和串联了所有的发布准备及后续操作。
使用场景：在项目需要发布新版本且工作区变更已全部提交时使用。通过直观的命令行交互完成发布。
核心流程：
- 交互式提示并确认发布版本号（自动计算 patch、minor 等升级维度）。
- 执行用户自定义的
task函数（例如修改文件，打包构建）。 - 自动更新项目中
package.json的版本号。 - 生成对应该版本的
Changelog。 - 自动完成 Git 提交动作并且打上新版本标签 (Tag)。
- 自动将更新后的包发布至 npm。
CMD 命令：
标志参考：
用法: vr release [标志...]
标志:
--remote string 远程仓库名称 # 默认: 'origin'
--skip-npm-publish 跳过 npm 发布
--skip-changelog 跳过生成变更日志
--skip-git-tag 跳过 git tag
--npm-tag string npm tag
--check-remote-version 检查远程版本
使用示例：
# 发布所有包并执行完整工作流程
pnpm exec vr release
# 跳过 npm 发布
pnpm exec vr release --skip-npm-publish
# 跳过生成变更日志
pnpm exec vr release --skip-changelog
# 检查远程版本，若已存在相同版本则中断执行
pnpm exec vr release --check-remote-version
# 指定推送 tag 的 git remote 名称（适用于配置了多个 remote 的场景，如 upstream、fork 等）
pnpm exec vr release --remote upstreamNode 调用：
import { release } from '@varlet/release'
release({
remote?: string // 远程仓库名称，默认为 'origin'
npmTag?: string // 发布的 npm tag，如 'next'、'alpha'
cwd?: string // 工作目录，默认为 process.cwd()
skipNpmPublish?: boolean // 是否跳过 npm publish 过程
skipChangelog?: boolean // 是否跳过生成变更日志
skipGitTag?: boolean // 是否跳过构建 git tag 过程
checkRemoteVersion?: boolean // 是否检查远程版本，保证不发生版本冲突
task?(newVersion: string, oldVersion: string): Promise<void> // 发布过程中执行的自定义任务
})例：增加自定义处理逻辑
import { release } from '@varlet/release'
async function task(newVersion, oldVersion) {
// 在此处执行构建或写入文件的操作
await doBuild()
}
release({ task })作用：单独将包发布至 npm 仓库。
使用场景：适用于无需手动选择版本、生成 Changelog 或打 Git Tag 的场景，常用于在 CI/CD 流水线中针对特定过程触发自动化发布。
核心流程：读取当前 package.json 中的版本号，运行对应的 publish 流程。
CMD 命令：
标志参考：
用法: vr publish [标志...]
标志:
--check-remote-version 检查远程版本
--npm-tag string npm tag
使用示例：
# 直接发布到 npm
pnpm exec vr publish
# 检查由于网络等原因是否已存在相同版本，存在则放弃发布
pnpm exec vr publish --check-remote-version
# 指定 npm 的 dist-tag
pnpm exec vr publish --npm-tag alphaNode 调用：
import { publish } from '@varlet/release'
publish({
preRelease?: boolean // 预发布标示，将添加 '--tag alpha' 选项
checkRemoteVersion?: boolean // 发布前检查远程 npm 上是否已存在相同版本
npmTag?: string // 发布的 npm tag
cwd?: string // 工作目录，默认为 process.cwd()
})作用：基于规范的 Commit 历史自动生成 Markdown 格式的变更日志。
使用场景：单独更新 CHANGELOG.md 记录，单点生成所需日志。
核心流程：遍历 Git 提交历史，依据预设的 conventional commit 规则分类（如 feat、fix 等），格式化输出。
CMD 命令：
标志参考：
用法: vr changelog [标志...]
标志:
--release-count number 发布数量 # 默认: 0
--file string 变更日志文件名 # 默认: 'CHANGELOG.md'
使用示例：
# 生成所有历史的变更日志并在当前目录输出为 CHANGELOG.md
pnpm exec vr changelog
# 指定生成的变更日志文件名
pnpm exec vr changelog --file my-changelog.md
# 限定发布版本的范围数量以生成变更日志 (0 为全量)
pnpm exec vr changelog --release-count 0Node 调用：
import { changelog } from '@varlet/release'
changelog({
cwd?: string // 工作目录，默认为 process.cwd()
releaseCount?: number // 输出日志涉及的最近发布的版本数量，默认为 0（全部）
file?: string // 输出的日志文件名，默认为 'CHANGELOG.md'
showTypes?: string[] // 显示的 commit 类型，默认 ['feat', 'fix', 'perf', 'revert', 'refactor']
outputUnreleased?: boolean // 是否输出 unreleased 版本变更
writerOpt?: object // conventional-changelog-writer 具体配置参数
})作用：校验 Git 提交信息格式。
使用场景：结合 git hooks 一同工作，强制保障书写高质量的提交说明以保证 Changelog 质量。
核心流程：读取提交文件，若是符合配置的正则格式则通过处理，否则打印具体的失败信息报错，并终止提交。
CMD 命令：
参数参考：
用法: vr commit-lint <commit-message-path> [标志...]
参数:
<commit-message-path> Git commit message 路径（必填）
标志:
--commit-message-re string 验证 commit message 是否通过的正则表达式
--error-message string 验证失败时显示的错误信息
--warning-message string 验证失败时显示的警告信息
使用示例：
# 检测指路径的 commit message 是否符合规范
pnpm exec vr commit-lint .git/COMMIT_EDITMSG
# 定制指定的校验正则表达式和提示信息
pnpm exec vr commit-lint .git/COMMIT_EDITMSG --commit-message-re "^feat: .*" --error-message "提交校验失败"建议配合并在 package.json 中的 simple-git-hooks 或 husky 一同集成运作：
{
"simple-git-hooks": {
"commit-msg": "pnpm exec vr commit-lint $1"
}
}Node 调用：
import { commitLint } from '@varlet/release'
commitLint({
commitMessagePath: string // 必选：Git commit message 文件路径
commitMessageRe?: string | RegExp // 验证 msg 格式的正则表达式
errorMessage?: string // 验证失败时打印的提示文本
warningMessage?: string // 验证失败时打印的补充警告文档链接
})作用：检测并在控制台直观地输出前端依赖包的 lockfile 文件是否发生变更，并默认自动安装依赖以保持同步。
使用场景：通常在进行 git 操作 (如 git pull拉取最新代码、git checkout切换分支、或合并代码) 之后使用。它能帮助你检测上游的依赖锁文件（如 pnpm-lock.yaml）是否发生了变动。如果检测到有变更，默认会自动执行 install 安装命令，从而确保本地环境快速与上游依赖保持一致，避免因依赖版本陈旧导致的疑难 bug。
核心流程：比对项目原始游标的锁文件（如 pnpm-lock.yaml 或对应环境的 lockfile）的 Git diff，在控制台输出其是否存在变动；默认会触发包管理器的依赖重装程序以同步上游，也可以通过指令跳过安装。
CMD 命令：
标志参考：
用法: vr lockfile-check [标志...]
标志:
--package-manager string 包管理器 (npm, yarn, pnpm) # 默认: 'pnpm'
--skip-install 当 lockfile 发生变化时跳过安装依赖
使用示例：
# 检查当前 lockfile 的同步状态，若有变化则自动安装依赖
pnpm exec vr lockfile-check
# 检查当前状态，即使有更新也跳过安装
pnpm exec vr lockfile-check --skip-install
# 指定其他包管理器进行检查
pnpm exec vr lockfile-check --package-manager npm建议配合并在 package.json 中的 simple-git-hooks 或 husky 一同集成运作（例如在拉取代码的 post-merge 或 post-checkout 阶段自动触发检查与安装）：
{
"simple-git-hooks": {
"post-merge": "pnpm exec vr lockfile-check"
}
}Node 调用：
import { lockfileCheck } from '@varlet/release'
lockfileCheck({
packageManager?: 'npm' | 'yarn' | 'pnpm' // 选择包管理器，默认为 'pnpm'
skipInstall?: boolean // 检测到 lock 不同步时是否跳过安装
})