在 Node.js 脚本中以编程方式使用 release-it：API 调用、输出对象与底层实现

开发工具DevOps【免费下载链接】release-it Automate versioning and package publishing项目地址https://gitcode.com/gh_mirrors/re/release-it点击查看免费下载release-it 不仅是一款交互式 CLI 发布工具其核心引擎也以编程 API 的形式对外暴露允许你在自己的 Node.js 脚本、构建流水线或自定义工具链中直接驱动“版本号递增 → 打标签 → 发布”的完整流程。本文以官方配方文档 docs/recipes/programmatic.md 为主线结合 lib/index.js、lib/config.js、lib/args.js 等源码实现讲解编程式调用的入口、options 参数语义、返回值结构以及依赖注入等进阶用法读完即可在自己的脚本中可靠地集成 release-it。为什么需要编程式调用release-it 的大多数用户通过npm run release或npx release-it使用 CLI但存在两类场景需要把它当作库来用嵌入已有脚本你的发布流程还需要在 release-it 之前或之后执行额外的 Node 逻辑把版本号、changelog 等中间结果传给其他工具复用同一套配置与逻辑程序化调用与 CLI 共用完全相同的配置体系、插件体系和执行引擎不需要重新实现“从 package.json 读取版本、按 Git 标签计算增量”等逻辑。从源码结构看这并非两套独立的实现CLI 入口 lib/cli.js 在解析完命令行参数后只是简单地把 options 转交给runTasks(options)而runTasks正是lib/index.js的默认导出。也就是说CLI 与编程 API 是同一个函数的不同调用方式。安装与模块形态以编程方式使用前先把 release-it 安装为项目依赖npm install -D release-itrelease-it 本身是 ESM 模块package.json中type: module其导出映射exports字段将包根路径指向lib/index.js同时提供require与import两种加载方式类型声明位于 types/index.d.ts。因此推荐在你的脚本中使用 ESM 语法导入import release from release-it;基本用法官方配方文档给出的核心示例即是最小可用形式import release from release-it; release(options).then(output { console.log(output); // { version, latestVersion, name, changelog } });release(options)返回一个 Promise成功时兑现为包含version、latestVersion、name、changelog四个字段的输出对象。由于是异步函数也可以直接awaitimport release from release-it; try { const output await release(options); console.log(发布版本${output.version}); } catch (err) { console.error(发布失败${err.message}); }关于错误处理需要说明从 lib/index.js 的源码可以看到runTasks内部捕获异常后会根据err.cause INFO决定以 info 还是 error 级别输出日志然后重新抛出该错误。因此调用方必须用try/catch或.catch()兜底否则未捕获的拒绝会直接中断进程。options 参数与 CLI 完全同一套配置对象release(options)中的options与命令行参数一一对应。以lib/args.js中parseCliArguments产出的对象为准常用的有选项类型含义incrementstring递增幅度major、minor、patch或pre*也可直接给出版本号CLI 中release-it minor是--incrementminor的简写dryRunboolean只展示将要执行的命令不实际改动任何内容ciboolean无提示、无交互在 CI 环境中会自动置为trueonlyVersionboolean仅用一次提示确定版本号其余步骤自动化changelogboolean仅打印本次发布对应的 changelog 后退出releaseVersionboolean仅打印下一个版本号后退出configstring | false本地配置文件路径默认.release-it传false可禁用配置文件加载hooksobject钩子脚本如hooks[after:release]git、github、gitlab、npm、pluginsobject各插件配置支持嵌套路径例如在脚本中模拟一次带minor递增的干跑不写任何文件、不执行任何发布动作import release from release-it; const output await release({ ci: true, dryRun: true, increment: minor }); console.log(output.latestVersion); // 当前最新版本 console.log(output.version); // 计算出的下一个版本再如完全绕过本地配置文件、强制以指定参数执行await release({ config: false, ci: true, increment: patch, git: { tag: true, push: true }, npm: { publish: false } });options 与本地配置、默认配置的合并规则这是理解编程式调用行为的关键。在 lib/config.js 的loadOptions中配置按以下优先级合并const merged defu( {}, constructorConfig, // 编程方式传入的 options优先级最高 { ci: isCI }, // 环境自动注入的 CI 标志 localConfig, // 本地配置文件如 .release-it / package.json 的 release-it 字段 defaultConfig // 内置默认配置 config/release-it.json );由此可以确认三条行为规则编程传入的 options 优先于本地配置文件——这与直觉相反但确实是设计如此constructorConfig排在最前defu只对缺失的键应用后续默认值本地配置文件依然会被加载loadLocalConfig使用c12以release-it为名查找配置默认从process.cwd()读取.release-it含.json、.yaml、.yml、package.json的release-it字段等除非显式传入config: false内置默认值来自仓库根目录的 config/release-it.json所有未指定项最终都有兜底。因此编程式调用既可以“全部在 options 里显式声明”也可以“只覆盖少量参数、其余交给本地配置与默认配置”两种风格与 CLI 完全等价。需要注意的退出行为changelog: true与releaseVersion: true两个选项在 lib/index.js 和 lib/index.js 中会触发process.exit(0)changelog 为空时process.exit(1)。这适合 CLI 场景但如果在守护进程或长任务中编程调用应避免使用这两个选项改用返回值自行处理。返回值 output 对象详解输出对象的四个字段定义在 lib/index.js由执行引擎在流程末尾统一组装return { name, changelog, latestVersion, version };各字段含义与来源字段含义取值依据源码name项目名称通过reduceUntil(plugins, plugin plugin.getName())获得通常来自package.json的name若所有插件均未返回则为undefinedlatestVersion发布前的当前最新版本getLatestVersion()的结果任何插件均未返回时兜底为0.0.0见 lib/index.jsversion本次计算出的新版本有increment时由getIncrementedVersionCI/getIncrementedVersion计算increment: false等价 CLI 的--no-increment时等于latestVersion若无可发布的新版本则为undefinedchangelog本次发布对应的 changelog 文本getChangelog(latestVersion)的结果默认基于git log生成可被git.changelog或github.releaseNotes/gitlab.releaseNotes覆盖注意当没有任何新版本可发布时version为undefined引擎会打印No new version to release并正常完成 Promise见 lib/index.js所以调用方应把version undefined视为“无需发布”的正常分支而非错误。从 test/plugins.js 的测试断言也可以印证返回结构一次完整流程后测试期望result恰好等于{ changelog: undefined, name: new-project-name, latestVersion: 1.2.3, version: 1.3.0 }。进阶用法依赖注入容器runTasks的函数签名实际上是runTasks(opts, di)第二个参数di是一个依赖注入容器。这在 lib/index.js 中体现得很明显容器内可以预置config、log、spinner、prompt、shell等组件未提供的部分会在运行时按需创建。测试代码 test/plugins.js 展示了标准用法const getContainer options { const config new Config(Object.assign({}, testConfig, options)); const shell new ShellStub({ container: { log, config } }); return { log, spinner, config, shell }; }; const result await runTasks({}, container);这对两类场景有价值单元测试注入 mock 的shell、log、spinner在完全不触碰真实 Git、npm、网络的前提下验证发布流程与插件生命周期调用顺序宿主应用集成复用自己定制的 Logger、Shell 或 Prompt 实现让 release-it 的日志、命令执行与宿主应用保持一致。不过Config、Plugin等类也都从包入口导出见 lib/index.js 的export { default as Config }与export { default as Plugin }因此也可以脱离runTasks直接使用Config完成配置解析。编程式调用与 CLI 行为的一致性理解“同一引擎”这一点可以帮你推断编程式调用的行为交互性未传ci: true时在终端环境下依然会弹出交互提示版本选择、任务确认等传ci: true或处于 CI 环境lib/config.js 中用ci-info检测时完全自动化钩子与插件hooks、plugins配置照常生效外部插件同样会被 lib/plugin/factory.js 加载并参与完整的生命周期init→beforeBump→bump→beforeRelease→release→afterRelease干跑dryRun: true与 CLI 的--dry-run等价会打印将要执行的命令而不触碰任何资源详细语义见 docs/dry-runs.md配置体系所有可配置项Git 提交信息、标签规则、npm 发布参数、GitHub/GitLab Release 选项等均可在 options 中按嵌套结构传递完整清单与默认值见 config/release-it.json 与 docs/configuration.md。小结release-it 的编程 API 与其 CLI 共享同一个执行引擎import release from release-it后传入与 CLI 参数同构的 options 对象即可获得{ version, latestVersion, name, changelog }四个关键产出options 的优先级为“程序传入 CI 标志 本地配置 内置默认配置”高级场景还可通过第二个参数注入config、shell、log等依赖实现对发布流程的可测试、可定制集成。无论是把版本号喂给下游构建工具还是在自定义发布编排中复用 release-it 的全部能力这份 API 都是 CLI 之外的可靠入口。赞分享开发工具DevOps【免费下载链接】release-it Automate versioning and package publishing项目地址https://gitcode.com/gh_mirrors/re/release-it点击查看免费下载相关推荐fuels-rs 合约调用中的输出变量Variable Outputs指南with_variable_output_policy 的使用与底层实现fuels rs 合约调用中的输出变量Variable Outputs指南 with_variable_output_policy 的使用与底层实现 本文区块链Web3OneUptime CLI 输出格式完全指南table、JSON 与 wide 的使用与底层实现OneUptime CLI 输出格式完全指南table、JSON 与 wide 的使用与底层实现 本篇技术指南围绕 OneUptime 官方 CLI one可观测性后端运维前端云原生微服务AI Agent使用 EntitySchema 在 MikroORM 中以编程方式定义实体使用 EntitySchema 在 MikroORM 中以编程方式定义实体 导读 EntitySchema 是 MikroORM 提供的一种 去装饰器化的实体定后端上一篇Sa-Token SSO 无 SDK 对接指南NoSdk、ReSdk 模式与非 Java 项目接入认证中心下一篇ctf-wiki Android 逆向指南Smali 语法与 Dalvik 字节码指令全解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考