@neosjs/release
通用的发布 CLI 工具,自动执行与版本控制和包发布相关的任务:版本管理(package.json)、Git 提交 / 打标签 / 推送、生成更新日志(CHANGELOG.md)、发布到 npm、在 GitHub 或 GitLab 创建 Release、管理预发行版,并可通过 Hooks 执行任意(测试或构建)命令,从任何 CI/CD 环境中发布。
安装
推荐的安装方式是全局安装:
npm install @neosjs/release -gpnpm add -g @neosjs/release或者在项目中安装为开发依赖,并把 release 脚本添加到 package.json:
npm install @neosjs/release -D
# pnpm 方式
pnpm add @neosjs/release -D{
"name": "package",
"version": "1.0.0",
"scripts": {
"release": "release"
},
"devDependencies": {
"@neosjs/release": "latest"
}
}快速上手
从项目根目录运行:
npm run release
# 或
npx @neosjs/release全局安装过的用户可以直接运行:
release系统会提示选择新版本,随后根据配置提示更多信息。更多配置及使用说明:
release --help常用标志:
--only-changelog:只打印变更日志,不发布任何内容;--show-changelog:在交互界面打印日志内容;--show-changeset:在交互界面打印变更记录;--no-npm(或配置npm: false):不提升版本、不发布到 npm。
配置
开箱即用,所有选项均有默认值,配置文件里只放要覆盖的项。在项目根目录按以下顺序查找配置:
release.config.jsonrelease.config.tsrelease.config.js(或.cjs,导出配置对象)release.config.yaml(或.yml)release.config.toml
简单的 release.config.js 示例:
module.exports = {
git: {
push: true,
commitMessage: `chore: release v${version}`
}
}支持 TypeScript 配置文件,配合 defineConfig 获得输入提示:
import type { ConfigOptions } from '@neosjs/release'
import { defineConfig } from '@neosjs/release'
export default defineConfig({
changelog: {
generate: true,
header: '# 更新日志\n\n此变更日志使用 `@neosjs/release` 自动更新.\n',
infile: 'CHANGELOG.md'
},
npm: {
publish: false
}
}) satisfies ConfigOptionsGit
Git 项目会自动执行 stage、commit、tag、push 任务。默认流程:
- 先决条件检查(验证是否有 Git、分支、工作目录、上游分支);
git add . --update;git commit -m "[git.commitMessage]";git tag --annotate --message="[git.tagAnnotation]" [git.tagName];git push [git.pushArgs] [git.pushRepo]。
不在 CI 模式时,每次提交、打标签和推送步骤之前都会请求确认。
git 配置选项
| 配置 | 描述 |
|---|---|
git.logCommand | 变更日志生成命令 |
git.requireCleanWorkingDir | 要求提交所有文件更改 |
git.requireBranch | 要求发布在特定的分支名称上 |
git.requireUpstream | 要求上游远程存在 |
git.requireCommits | 如果自上次发布以来没有提交,则停止该过程 |
git.requireCommitsFail | 如果没有提交,则继续但使用退出码 0 |
git.commitsPath | 发布版本中应包含的目录路径发生变化 |
git.addUntrackedFiles | 将未跟踪的文件添加到发布提交 |
git.commit | 如果 false,跳过提交发布步骤 |
git.commitMessage | 添加到提交步骤的消息 |
git.commitArgs | 为 git commit 提供额外的参数 |
git.tag | 如果 false,跳过标签发布步骤 |
git.tagExclude | 覆盖正常行为以查找最新标签 |
git.tagName | 自定义标签名称,可能与(前缀)版本不同 |
git.tagMatch | 覆盖正常的匹配行为来查找最新的标签 |
git.getLatestTagFromAllRefs | 获取所有标签(可直接访问或不可直接访问,按版本排序) |
git.tagAnnotation | 用于注释 Git 标签的消息字符串 |
git.tagArgs | 为 git tag 提供额外的参数 |
git.push | 如果 false,跳过推送发布步骤 |
git.pushArgs | 为 git push 提供的额外参数 |
git.pushRepo | 将发布推送到的远程名称或 Git URL(默认 origin) |
发布到 npm
在项目目录中,@neosjs/release 会提升 package.json 的 version 字段并发布到 npm 注册表。为防止后续过程中出现问题,它会先检查 npm 注册表是否可用、用户是否已通过认证以及是否是当前包的合作者。某些 npm 注册表实例(例如 Nexus)不支持 npm ping、npm whoami 和 / 或 npm access;如果错误是 E400 或 E404,工具会发出警告但继续。要跳过这些检查,使用 npm.skipChecks。
| 选项 | 描述 |
|---|---|
npm.publish | 设置为 false 跳过 npm publish 步骤 |
npm.publishPath | 仅发布特定文件夹(例如 dist) |
npm.publishArgs | 为 npm 提供额外的参数来进行发布操作 |
npm.tag | 在 npm 存储库中标记包,例如 npm.tag=beta |
npm.otp | 从命令行提供一次性密码(OTP),例如 npm.otp=123456 |
npm.ignoreVersion | 设置为 true 时忽略来自 package.json 的 version |
npm.allowSameVersion | 允许新版本与当前版本具有相同的值 |
npm.skipChecks | 跳过 npm 注册表与用户权限检查 |
更新日志
默认自动生成变更日志,用于展示并帮助选择新版本,同时作为 GitHub 或 GitLab Release 的发布说明。默认命令基于 git log,可通过 git.logCommand 覆盖;要进一步定制发布说明,可设置 github.releaseNotes 或 gitlab.releaseNotes。注意,默认情况下 @neosjs/release 与提交消息约定无关。