准备第一次发布

运行条件

Verso 要求 Node.js 22.18 或更高版本，并支持以下平台：

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

安装 Verso

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

pnpm add -D @amamo/verso

npm install -D @amamo/verso

yarn add -D @amamo/verso

bun add -d @amamo/verso

参考文档统一用 verso ... 表示 CLI 参数，避免绑定某一种 package manager。请通过安装 Verso 的 package manager 或项目已有任务调用本地 executable。

判断是否需要配置文件

单包项目只需要根目录存在 package.json、package.json5、package.yaml、package.yml 或 oh-package.json5。鸿蒙应用使用 AppScope/app.json5，并从 build-profile.json5 发现模块。 没有显式传入 --config 时，Verso 会采用内置默认值。

Workspace 项目可以生成 verso.toml：

verso init

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

verso init --workspaceverso init --single

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

检查发布条件

通过安装 Verso 的 package manager 运行第一次检查：

pnpm exec verso doctor

npm exec --package=@amamo/verso -- verso doctor

yarn exec verso doctor

bunx --no-install verso doctor

doctor 会检查配置加载、package 发现、当前版本、共享的 package 和 Cargo 版本、changelog 父目录， 以及具名分支的 upstream。任一检查失败都会返回非零退出状态。后续示例用 verso 作为同一本地 executable 的简写。自动化可以读取同一组检查的 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 或宽松工作区策略的仓库，在自动化前应先阅读 发布流程。