Skip to content

@neosjs/release ​

通用的发布 CLI 工具,自动执行与版本控制和包发布相关的任务:版本管理(package.json)、Git 提交 / 打标签 / 推送、生成更新日志(CHANGELOG.md)、发布到 npm、在 GitHub 或 GitLab 创建 Release、管理预发行版,并可通过 Hooks 执行任意(测试或构建)命令,从任何 CI/CD 环境中发布。

安装 ​

推荐的安装方式是全局安装:

sh
npm install @neosjs/release -g
sh
pnpm add -g @neosjs/release

或者在项目中安装为开发依赖,并把 release 脚本添加到 package.json:

sh
npm install @neosjs/release -D

# pnpm 方式
pnpm add @neosjs/release -D
json
{
  "name": "package",
  "version": "1.0.0",
  "scripts": {
    "release": "release"
  },
  "devDependencies": {
    "@neosjs/release": "latest"
  }
}

快速上手 ​

从项目根目录运行:

sh
npm run release
# 或
npx @neosjs/release

全局安装过的用户可以直接运行:

sh
release

系统会提示选择新版本,随后根据配置提示更多信息。更多配置及使用说明:

sh
release --help

常用标志:

  • --only-changelog:只打印变更日志,不发布任何内容;
  • --show-changelog:在交互界面打印日志内容;
  • --show-changeset:在交互界面打印变更记录;
  • --no-npm(或配置 npm: false):不提升版本、不发布到 npm。

配置 ​

开箱即用,所有选项均有默认值,配置文件里只放要覆盖的项。在项目根目录按以下顺序查找配置:

  • release.config.json
  • release.config.ts
  • release.config.js(或 .cjs,导出配置对象)
  • release.config.yaml(或 .yml)
  • release.config.toml

简单的 release.config.js 示例:

js
module.exports = {
  git: {
    push: true,
    commitMessage: `chore: release v${version}`
  }
}

支持 TypeScript 配置文件,配合 defineConfig 获得输入提示:

ts
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 ConfigOptions

Git ​

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 与提交消息约定无关。