# 使用 Stripe CLI

通过命令行构建、测试和管理您的 Stripe 集成。

更多详情请参阅 [Stripe CLI 参考](https://docs.stripe.com/cli.md)。

通过 Stripe CLI，您可以从命令行构建、测试和管理您的 Stripe 集成。使用 CLI，您可以创建和管理 Stripe 资源、触发 Webhook 事件、流式传输实时 API 请求日志，以及将事件转发到您的本地开发环境。

## 在运行请求时指定 API 版本。

当您在 CLI 中调用 Stripe API 时，它会在所有请求中使用您的默认 API 版本，您可以在 [Workbench](https://docs.stripe.com/workbench/guides.md#view-api-versions) 中识别该版本。要在 CLI 中试用不同的 API 版本，请使用以下标志：

| 标志                                   | 描述                                              | 示例                                                                              |
| ------------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------- |
| `--stripe-version 2026-03-25.dahlia` | 在任何 CLI 请求中，使用 `--stripe-version` 标志来指定 API 版本。 | `stripe products create --name=“My Product” --stripe-version 2026-03-25.dahlia` |
| `--latest`                           | 在任何 CLI 请求中，使用 `--latest` 标志来指定最新的 API 版本。      | `stripe products create --name="My Product" --latest`                           |

您还可以[查看 API 版本列表](https://docs.stripe.com/upgrades.md#api-versions)。

## 了解命令选项

要了解特定命令的选项，请在命令后添加 `--help`。

```bash
   stripe listen --help
```

## 流式传输请求日志

使用 `stripe logs tail` 命令来流式传输 API 请求日志。保持此窗口打开。如果 API 调用中出现错误，此终端将返回 API 错误消息以及错误原因。

```bash
  stripe logs tail
```

## 将事件转发到您的本地 Webhook 端点

使用 `--forward-to` 标志，将 **沙盒** 中的所有 [Stripe 事件 ](https://docs.stripe.com/cli/trigger#trigger-event) 发送到您的本地 Webhook 端点。要禁用 HTTPS 证书验证，请使用 `--skip-verify` 标志。

```bash
  stripe listen --forward-to localhost:4242/webhooks
```

```bash
  Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
```

要转发以逗号分隔的特定事件，请使用 `--events` 标志。

```bash
stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,charge.succeeded,checkout.session.completed,charge.failed \
  --forward-to localhost:4242/webhook
```

如果您已经在 [Stripe 中注册了您的端点](https://docs.stripe.com/webhooks.md#register-webhook)，则可以使用 `--load-from-webhooks-api` 和 `--forward-to` 标志。

```bash
stripe listen --load-from-webhooks-api --forward-to localhost:4242
```

此命令会将发送到您在 Stripe 注册的**公共** Webhook 端点的事件转发到您的**本地** Webhook 端点。它会加载您注册的端点，解析路径及其注册的事件，然后将路径附加到 `--forward-to` 路径中的本地 Webhook 端点。如果要检查 Webhook 签名，请使用 `listen` 命令初始输出中的`{{WEBHOOK_SIGNING_SECRET}}`。

## 列出所有可用事件

使用 [help 标志 ](https://docs.stripe.com/cli/help) (`--help`) 列出某一事件类别可能发生的所有事件。例如，列出 [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) 的[预构建结账页面](https://docs.stripe.com/checkout/quickstart.md)的所有可能事件：

```bash
  stripe trigger checkout --help
```

## 创建一次性产品和价格

1. 向[创建产品](https://docs.stripe.com/api/products/create.md)发送单个 API 请求。

   ```bash
   stripe products create \
   --name="My First Product" \
   --description="Created with the Stripe CLI"
   ```

1. 在响应对象中查找产品标识符（位于 `id` 中）。将其保存以备下一步使用。如果一切正常，命令行将显示以下响应：

   ```json
   {
     "id": "prod_LTenIrmp8Q67sa", // 标识符如下所示。
     "object": "product",
     "active": true,
     "attributes": [],
     "created": 1668198126,
     "default_price": null,
     "description": "Created with the Stripe CLI",
     "identifiers": {},
     "images": [],
     "livemode": false,
     "metadata": {},
     "name": "My First Product",
     "package_dimensions": null,
     "price": null,
     "product_class": null,
     "shippable": null,
     "sku": "my-first-product-10",
     "statement_descriptor": null,
     "tax_code": null,
     "type": "service",
     "unit_label": null,
     "updated": 1668198126,
     "url": null
   }
   ```

1. 调用[创建价格](https://docs.stripe.com/api/prices/create.md)，附加 30 美元的价格。将 `product` 中的占位符替换为您的产品标识符（例如，`prod_LTenIrmp8Q67sa`）。

   ```bash
   stripe prices create \
     --unit-amount=3000 \
     --currency=usd \
     --product="{{PRODUCT_ID}}"
   ```

1. 如果一切正常，命令行将显示以下响应：

   ```json
   {
     "id": "price_1KzlAMJJDeE9fu01WMJJr79o", // 标识符如下所示。
     "object": "price",
     "active": true,
     "billing_scheme": "per_unit",
     "created": 1652636348,
     "currency": "usd",
     "livemode": false,
     "lookup_key": null,
     "metadata": {},
     "nickname": null,
     "product": "prod_Lh9iTGZhb2mcBy",
     "recurring": null,
     "tax_behavior": "unspecified",
     "tiers_mode": null,
     "transform_quantity": null,
     "type": "one_time",
     "unit_amount": 3000,
     "unit_amount_decimal": "3000"
   }
   ```

## 在测试时触发 Webhook 事件

触发 `checkout.session.completed` 事件，以创建因结账会话成功完成而产生的 API 对象。

```bash
stripe trigger checkout.session.completed
```

您的 `Stripe listen` 终端将显示以下输出：

```bash
Setting up fixture for: checkout_session
Running fixture for: checkout_session
Setting up fixture for: payment_page
Running fixture for: payment_page
Setting up fixture for: payment_method
Running fixture for: payment_method
Setting up fixture for: payment_page_confirm
Running fixture for: payment_page_confirm
Trigger succeeded!
```