---
description: 安装 Verso、初始化发现规则、检查仓库，并预览准确的发布计划。
---

# 准备第一次发布

## 运行条件

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

| 操作系统     | CPU          |
| ------------ | ------------ |
| macOS        | arm64 或 x64 |
| Linux（GNU） | arm64 或 x64 |
| Windows      | x64          |

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

## 安装 wrapper

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

```sh
# 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`：

```sh
verso init
```

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

```sh
verso init --workspace
verso init --single
```

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

## 检查发布条件

```sh
verso doctor
```

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

```sh
verso doctor --json
```

## 预览一个准确版本

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

```sh
verso --dry-run --version 1.4.0
```

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

```sh
verso --dry-run --version 1.4.0 --json
```

<Callout variant="warning" title="预览会显示 hook 命令">
  不要把 token 或密码写进 `verso.toml`。为了让计划可检查，dry-run 会有意输出每条 hook 命令。
</Callout>

## 执行发布

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

```sh
verso
```

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

```sh
verso --version 1.4.0 --yes
```

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