---
title: "通过 CLI 运行 A/B 测试"
description: "使用 Adapty CLI 在终端中创建、启动、停止、替换和归档付费墙及流程的 A/B 测试，并在每个不可撤销的步骤前预览实际效果。"
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

Adapty CLI 通过 `adapty ab-tests` 命令主题，在终端中运行付费墙或流程的常规 [A/B 测试](ab-tests)。你可以将测试创建为草稿，在某个版位针对某个目标受众启动测试，选定赢家后停止测试，用修改后的测试替换正在运行的测试，以及归档旧测试。

使用它让 AI 代理运行你的测试、跨多个应用编写测试脚本，或者无需打开看板即可启动或停止测试。

常规测试会将某个版位中某个目标受众的用户，分流到两个或多个付费墙，或两个或多个流程之间进行测试。如需跨多个版位运行测试，请在看板中使用[跨版位测试](ab-test-types)。`ab-tests` 命令不会返回测试结果。如需查看最优概率等结果，请前往看板：[A/B 测试结果与数据图表](results-and-metrics)。如需读取某个测试的用户分析数据，请通过 `adapty analytics catalog` 中的 **A/B tests** 维度对[分析命令](developer-cli-analytics)进行筛选。

## 开始之前 \{#before-you-start\}

`ab-tests` 主题与 CLI 的其他部分使用相同的安装和登录方式。如果尚未完成配置，请按照[快速入门指南](developer-cli-quickstart)中的步骤 1 和步骤 2 操作。该主题需要 CLI 0.14.0 或更高版本。要查看当前版本，请运行 `adapty --version`。

每条命令都需要通过 `--app` 传入应用的 UUID。要找到它，请运行：

```bash
adapty apps list
```

A/B 测试所使用的内容必须已经存在：

- **流程（Flows）**：流程只有在发布后才能加入测试。草稿状态或有未发布更改的流程将被拒绝。如需发布流程，请运行 `adapty flows publish`。
- **付费墙（Paywalls）**：如需使用 Adapty 中已有的产品创建付费墙，请运行 `adapty paywalls create`。如需为付费墙设计新样式，请使用[付费墙编辑工具](adapty-paywall-builder)。
- **版位（Placements）**：付费墙测试在付费墙版位上运行，流程测试在流程版位上运行。如需创建版位，请运行 `adapty placements create`。在应用代码获取新版位之前，该版位不会向用户展示任何内容。
- **市场细分（Segments）**：如需仅针对部分用户运行测试，请先使用 `adapty segments create` 创建[市场细分](segments)。

有关这些命令，请参阅[命令参考](developer-cli-reference)。

## 列出和读取测试 \{#list-and-read-tests\}

`list` 默认显示流程测试，除非你传入 `--type paywall`。要查看某个应用的所有测试，请分别执行以下命令：

```bash
adapty ab-tests list --app <app-id> --type flow --page-size 100
```

```bash
adapty ab-tests list --app <app-id> --type paywall --page-size 100
```

测试的状态包括以下几种：`draft`、`live`、`completed`、`inactive` 或 `archived`。

要读取某个测试及其实验分组，请运行：

```bash
adapty ab-tests get --app <app-id> <test-id>
```

在 `get --json` 中，`segment_ids` 表示测试的目标受众：`[]` 代表所有用户，`null` 表示尚未设置受众。每个实验变体包含其 `weight` 以及对应的付费墙或流程 ID。如需识别某个实验变体，请使用 `paywall_title` 或 `flow_name`。实验变体的 `title` 默认为空，除非你手动设置。

## 创建测试 \{#create-a-test\}

新测试以草稿形式存在。草稿对任何用户均不可见，因此你可以随时创建和修改。

1. **查找内容 ID**，使用 `adapty paywalls list` 或 `adapty flows list`。

2. **创建草稿**，包含两个或更多实验分组。每个分组对应一个付费墙或流程，并附有权重。权重表示看到该分组的用户比例，所有权重之和必须等于 100：

   ```bash
   adapty ab-tests create --app <app-id> --title "Annual vs monthly" \
     --goal "More revenue per user" --placement <placement-id> \
     --paywalls '[{"paywall_id":"<paywall-a>","weight":50},{"paywall_id":"<paywall-b>","weight":50}]'
   ```

   `--placement` 为必填项。付费墙测试需要付费墙版位，流程测试需要流程版位。如需进行流程测试，请传入 `--flows` 并在每个分组中使用 `flow_id`。分组还可以包含 `title` 字段，例如 `"title":"A"`。

3. **使用 `ab-tests get` 查看草稿**。

草稿的版位仅为计划状态。`create` 也可以接受计划中的目标受众，通过 `--segment` 或 `--all-users` 指定。这些计划值不会对用户产生任何影响。启动测试时，请再次将版位和目标受众传递给 `start`。

## 开始测试 \{#start-a-test\}

:::warning
开始后无法撤销。测试一旦启动，你指定的目标受众中的用户将不再看到他们当前的付费墙或流程。
:::

要启动草稿，需指定版位和一个目标受众：`--all-users`，或通过 `--segment` 指定一个市场细分 ID：

```bash
adapty ab-tests start --app <app-id> <test-id> --placement <placement-id> --segment <segment-id>
```

CLI 会打印本次启动的具体操作，并在发送任何内容之前询问 `Apply? [y/N]`。测试运行的位置取决于版位的目标受众配置：

- **版位中已有该市场细分的目标受众**（或"所有用户"）：测试将在该目标受众中运行。当前在此处运行的测试将停止并进入 `completed` 状态。
- **版位中没有该市场细分的目标受众**：`start` 会在版位上添加一个优先级最高的新目标受众。当前属于该市场细分且匹配其他目标受众的用户将被纳入本次测试。

要使测试的优先级低于另一个目标受众，请先将该市场细分作为目标受众添加，并设置相应优先级。为其分配这些用户当前看到的付费墙或流程，然后在该目标受众上启动测试。请参阅[更改目标受众优先级](change-audience-priority)。

市场细分目标受众的变更最多需要 20 分钟才能传达到所有用户。

只有草稿状态的测试才能启动。如需再次运行测试，请创建新测试：先用 `get` 读取旧测试，再用 `create` 以相同的实验变体创建一个新测试。

## 修改测试 \{#change-a-test\}

`update` 会重新提交整个测试。每次都需要传入所有参数，包括必填的 `--placement`。如果遗漏某个参数，Adapty 会清除对应的值，例如目标或已规划的目标受众。

```bash
adapty ab-tests update --app <app-id> <test-id> --title "Annual vs monthly, Q4" \
  --goal "More revenue per user" --placement <placement-id> \
  --paywalls '[{"paywall_id":"<paywall-a>","weight":70},{"paywall_id":"<paywall-b>","weight":30}]'
```

在实时测试中，`update` 仅更改标题和目标。传入的实验组、版位和目标受众必须与 `get` 返回的完全一致；传入其他实验组或其他版位将被拒绝。测试的开始时间保持不变，用户的实验组分配也不会改变。已完成或已归档的测试无法更改。

如需更改实时测试的实验组或权重，请使用替换操作。`replace` 对应看板中的 **Modify** 操作：

```bash
adapty ab-tests replace --app <app-id> <test-id> --title "Annual vs monthly v2" \
  --placement <placement-id> \
  --paywalls '[{"paywall_id":"<paywall-a>","weight":80},{"paywall_id":"<paywall-b>","weight":20}]'
```

正在运行的测试会停止并转为 `completed` 状态，其结果保留在原 ID 下。一个新的测试以新 ID 在相同目标受众上启动，Adapty 会重新为该目标受众中的每位用户分配实验变体。如果在 `--placement` 中传入不同的版位，Adapty 会将目标受众移至该版位。"所有用户"测试无法移动。

## 停止测试 \{#stop-a-test\}

`stop` 命令用于结束测试。你需要选择测试结束后，该目标受众的用户将看到什么内容。以下标志恰好传一个：

| 标志 | 停止后的效果 |
|---|---|
| `--winner <id>` | 整个目标受众将看到测试某个分支的内容。传入该分支的付费墙 ID 或 flow ID。 |
| `--other <id>` | 整个目标受众将看到一个未参与本次测试的付费墙或 flow，且类型需与测试相同。 |
| `--no-content` | 该目标受众从版位中移除，其用户将匹配下一个符合条件的目标受众。"所有用户"测试不支持此选项。 |

```bash
adapty ab-tests stop --app <app-id> <test-id> --winner <paywall-b>
```

测试将进入 `completed` 状态。如需再次测试相同的分组，请按照[启动测试](#start-a-test)中的说明创建新测试。如需选择获胜方，请参阅 [A/B 测试结果与数据图表](results-and-metrics)。

## 归档测试 \{#archive-a-test\}

您可以归档任何未上线的测试。如需归档正在运行的测试，请先停止它。归档后的测试无法恢复。

```bash
adapty ab-tests archive --app <app-id> <test-id>
```

## 脚本和代理中的确认操作 \{#confirmation-in-scripts-and-agents\}

`start`、`stop`、`replace` 和 `archive` 操作不可撤销，因此每个命令在发送请求前都会显示其影响。确认方式取决于命令的运行方式：

| 命令运行方式 | 执行结果 |
|---|---|
| 在终端中 | CLI 打印操作效果并询问 `Apply? [y/N]`。如果回答 `y` 或 `yes`，CLI 发送请求。其他任何回答，CLI 以代码 1 退出且不发送任何内容。 |
| 使用 `--yes` | CLI 无需询问直接发送请求。 |
| 使用 `--json`、在管道中或无终端时 | CLI 不发送任何内容并以代码 6 退出。错误信息会描述操作效果。 |

这样，脚本或代理就可以先了解命令的效果：先不带 `--yes` 运行，读取提示信息，待人工确认后再带 `--yes` 重新运行。

## 错误 \{#errors\}

| 退出代码 | 原因 | 解决方法 |
|---|---|---|
| 1 | 您在提示时输入了 `y` 以外的内容，未发送任何请求。 | 如需继续，请重新运行该命令。 |
| 2 | CLI 在发送前拒绝了输入：UUID 无效、arms 不是 JSON 数组、arm 缺少 ID 或整数权重、`--paywalls` 和 `--flows` 同时传入或均未传入，或指定了两个停止选项。 | 根据提示信息修正对应的参数。 |
| 3 | 您未登录，或您的 Adapty 用户无权访问该应用。 | 使用 `adapty auth login` 登录，并通过 `adapty apps list` 查找应用 ID。 |
| 4 | Adapty 拒绝了请求，消息中说明了原因。 | 请参阅 [来自 Adapty 的消息](#messages-from-adapty)。 |
| 5 | CLI 无法连接到 Adapty。 | 确认网络连接正常后重新运行命令。 |
| 6 | 某个不可撤销的命令在未传入 `--yes` 且无人响应的情况下运行，未发送任何请求。 | 阅读消息中的操作说明，然后加上 `--yes` 重新运行命令。 |
| 130 | 您在提示时按下了 Ctrl+C，未发送任何请求。 | — |

### 来自 Adapty 的消息 \{#messages-from-adapty\}

| 消息 | 处理方法 |
|---|---|
| `The sum of the weights must equal 100, but has N.` | 调整权重，使其总和等于 100。 |
| `Flow(<id>) must be published before adding to AB test.` | 先发布该流程，然后重新运行命令。 |
| `Paywalls cannot be changed in non-draft ab tests.` 或 `Placement cannot be changed in non-draft ab tests.` | 按 `get` 返回的原样传入 arms 和版位，或使用 `replace`。 |
| `AB Test from default audience can not be stopped.` | 面向全部用户的 A/B 测试停止后需要指定一个付费墙或流程：请使用 `--winner` 或 `--other`。 |
| `AB Test to stop must be live.` | 只有正在运行的 A/B 测试才能被停止或替换。 |
| `Live Ab Test can not be deleted.` | 请先停止 A/B 测试，再将其归档。 |

## 命令参考 \{#command-reference\}

每条命令都需要 `--app` 参数，即 `adapty apps list` 返回的应用 UUID。除 `list` 外，每条命令都需要将测试 ID 作为其参数。

### `ab-tests list`

| 标志 | 是否必填 | 描述 |
|---|---|---|
| `--type` | 否 | `flow`（默认）或 `paywall`。 |
| `--state` | 否 | `live`、`draft`、`completed`、`inactive` 或 `archived`。 |
| `--placement` | 否 | 仅显示该版位（ID）的测试。可重复使用该标志以指定多个版位。 |
| `--segment` | 否 | 仅显示针对该市场细分（ID）运行的测试。可重复使用该标志以指定多个市场细分。 |
| `--search` | 否 | 仅显示标题包含该文本的测试。 |
| `--page` | 否 | 页码。默认值：1。 |
| `--page-size` | 否 | 每页显示的测试数量，最多 100 条。默认值：20。 |

### `ab-tests get`

返回该测试及其实验变体。不接受其他标志。

### `ab-tests create`

| 参数 | 是否必填 | 说明 |
|---|---|---|
| `--title` | 是 | 测试标题。 |
| `--paywalls` | 二选一 | 付费墙测试的实验组，JSON 格式：`[{"paywall_id":"<id>","weight":50,"title":"A"}, …]`。`title` 为可选字段。 |
| `--flows` | 二选一 | 流程测试的实验组，JSON 格式，使用 `flow_id` 代替 `paywall_id`。 |
| `--goal` | 否 | 测试目标说明。 |
| `--placement` | 是 | 计划运行测试的版位（ID）。付费墙测试需要付费墙版位，流程测试需要流程版位。 |
| `--segment` | 否 | 针对某个市场细分运行测试（ID）。不可与 `--all-users` 同时使用。 |
| `--all-users` | 否 | 针对所有用户运行测试。 |

### `ab-tests update`

与 `create` 使用相同的参数，且 `--placement` 为必填项。省略某个参数时，该参数会被清除。对于正在运行的测试，只能修改 `--title` 和 `--goal`。请同时传入相同的版位和目标受众。

### `ab-tests start`

| 参数 | 是否必填 | 描述 |
|---|---|---|
| `--placement` | 是 | 运行测试的版位（ID）。 |
| `--segment` | 二选一 | 为某个市场细分运行测试（ID）。 |
| `--all-users` | 二选一 | 为所有用户运行测试。 |
| `--yes`, `-y` | 否 | 无需确认直接启动。使用 `--json` 或管道时必填。 |

### `ab-tests stop`

| 参数 | 是否必填 | 说明 |
|---|---|---|
| `--winner` | 三选一 | 向全部目标受众展示该实验组的付费墙或流程（ID）。 |
| `--other` | 三选一 | 展示一个不在本次测试中的付费墙或流程（ID）。 |
| `--no-content` | 三选一 | 从版位中移除该目标受众。对"所有用户"测试不可用。 |
| `--yes`, `-y` | 否 | 跳过确认直接停止。使用 `--json` 或在管道中运行时必填。 |

### `ab-tests replace`

| 标志 | 是否必填 | 描述 |
|---|---|---|
| `--title` | 是 | 新测试的标题。 |
| `--placement` | 是 | 新测试的版位（ID）。使用不同的版位会将目标受众移至该版位。 |
| `--paywalls` 或 `--flows` | 是 | 新测试的实验变体，用法与 `create` 相同。 |
| `--goal` | 否 | 新测试的目标说明。 |
| `--yes`, `-y` | 否 | 不询问直接替换。与 `--json` 一起使用或在管道中使用时必填。 |

新测试会继承被替换测试的目标受众，因此 `replace` 不接受目标受众标志。

### `ab-tests archive`

| 标志 | 是否必填 | 描述 |
|---|---|---|
| `--yes`, `-y` | 否 | 无需确认直接归档。在使用 `--json` 或管道时必须指定。 |

## 下一步 \{#whats-next\}

- [A/B 测试的智能体技能](ab-tests-skill) — 让你的智能体规划、启动和停止测试，每个不可撤销的步骤都需要你的确认。
- [创建、运行和停止 A/B 测试](run_stop_ab_tests) — 在看板中执行相同的步骤。
- [A/B 测试结果与数据图表](results-and-metrics) — 如何解读结果并选出胜出的实验变体。