准备第一次发布

运行条件

npm wrapper 要求 Node.js 22.18 或更高版本，并会为当前平台安装一个原生 optional dependency。

待发布仓库还需要 Git、至少一个受支持的 package manifest，以及配置了 upstream 的具名分支。真正发布时， 如果本地分支落后于 upstream，Verso 会拒绝继续。

安装 wrapper

使用你偏好的 package manager 在 workspace 根目录添加 Verso：

# npm
npm install --save-dev @amamo/verso
# pnpm
pnpm add --save-dev @amamo/verso
# Yarn
yarn add --dev @amamo/verso
# Bun
bun add --dev @amamo/verso

下面的示例直接使用 verso executable，不假设 package.json script 的名称。npm package 会解析当前 平台的 package，在 macOS 和 Linux 上按需修复 executable bit，再转发 CLI 的退出状态和信号。

判断是否需要配置文件

单包项目只需要根目录存在 package.json、package.json5、package.yaml 或 package.yml。没有显式传入 --config 时，Verso 会采用内置的单包默认值。

Workspace 项目可以生成 verso.toml：

verso init

初始化器只会通过 packages/*/package.json 判断 workspace 模式；其他目录结构应显式指定：

verso init --workspace
verso init --single

init 默认拒绝覆盖已有文件。只有确实要替换配置时才使用 --force。

检查发布条件

verso doctor

doctor 会检查配置加载、package 发现、当前版本、共享的 package 和 Cargo 版本、changelog 父目录， 以及具名分支的 upstream。任一检查失败都会返回非零退出状态。自动化可以读取同一组检查的 JSON：

verso doctor --json

预览一个准确版本

先指定目标版本，让预览可以复现：

verso --dry-run --version 1.4.0

计划会列出版本文件、可选的 changelog、已配置的 hook、警告、commit 与 tag 模板，以及 Git 命令的准确形态。 它不会写文件、运行 hook、创建 commit 或 tag，也不会推送。只有 dry-run 模式支持 JSON：

verso --dry-run --version 1.4.0 --json

执行发布

交互模式会提供 stable 和 prerelease 选项，并在写文件、提交、打 tag 和推送前分别确认：

verso

自动化应给出准确的 SemVer，并明确跳过全部确认：

verso --version 1.4.0 --yes

--yes 只跳过确认，永远不会选择版本。含有 hook 或宽松工作区策略的仓库，在自动化前应先阅读 发布流程。