upgrade-stripe

升级 Stripe 版本

选择目标 API 版本

如果用户指定了目标 API 版本，请使用该版本。否则，请使用你能访问的任何文档或 Web 工具，在 docs.stripe.com 上查询当前版本，例如使用 Stripe CLI 运行 stripe docs /api/versioning。API 版本控制页面会在以“The current version is”开头的句子中说明当前版本。

内置的备用 API 版本：2026-08-26.dahlia。此值仅是本技能上次生成时（2026-10-01）的快照。版本标识符以 YYYY-MM-DD 格式的发布日期开头，新稳定版本每月发布一次，因此，发布日期早于一个月的备用版本可能已经过时。只有在无法访问 docs.stripe.com 时才使用它。切勿猜测更新的版本号。

进行更改前，请将目标版本与集成固定的每个 API 版本进行比较：客户端配置、单请求覆盖设置和 Webhook 端点。除非用户明确要求，否则不要将任何固定版本降级，也不要将稳定版本切换为预览版本。如果某个固定版本已与目标版本一致，请报告其未更改。说明所选目标版本及其来源。如果无法进行实时验证或无法获取验证结果，请说明最新版本尚未验证，不要声称集成使用的是最新版本。

检查 Webhook 端点和事件目标时，请区分快照事件和精简事件。精简事件的载荷没有版本，因此更改 API 版本时无需升级。用于检索完整事件或相关资源的 API 调用仍然有版本。

对于支持显式 API 版本覆盖的 SDK，请在客户端配置和单请求覆盖设置中使用所选目标版本。curl 测试请求头 Stripe-Version 中也应使用该版本。复制或运行示例之前，请将其中内置的 API 版本替换为所选目标版本。对于 Java、Go 和 .NET，请选择面向所选 API 版本的 SDK 版本，而不要覆盖 SDK 的固定版本。预览目标需要所有语言中与之匹配的 beta SDK 版本；请参阅 SDK 版本控制。

了解 Stripe API 版本控制

Stripe 使用基于日期的 API 版本（例如 2026-08-26.dahlia、2025-08-27.basil、2024-12-18.acacia）。你账户的 API 版本决定请求和响应的行为。

从 2024-09-30.acacia 版本开始，Stripe 每月发布一个不含破坏性更改的新 API 版本。每年两次，Stripe 会推出一个新的主要版本（例如 Basil），其 API 版本包含破坏性更改。你可以安全地升级到任何月度版本，无需更新代码。

更改类型

向后兼容的更改（无需更新代码）：

• 新 API 资源
• 新的可选请求参数
• 现有响应中的新属性
• 不透明字符串长度的更改（例如对象 ID）
• 新 Webhook 事件类型

破坏性更改（需要更新代码）：

• 字段重命名或移除
• 行为修改
• 端点或参数移除

请查看 API 变更日志，了解版本之间的所有更改。完整升级指南请参阅 API 升级。

服务端 SDK 版本控制

有关如何在代码中设置 API 版本的详情，请参阅为 SDK 设置 Stripe API 版本。

动态类型语言（Ruby、Python、PHP、Node.js）

这些 SDK 提供灵活的版本控制：

全局配置：

import stripe
stripe.api_version = '2026-08-26.dahlia'

Stripe.api_version = '2026-08-26.dahlia'

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-08-26.dahlia'
});

单请求覆盖：

stripe.Customer.create(
  email="[email protected]",
  stripe_version='2026-08-26.dahlia'
)

强类型语言（Java、Go、.NET）

这些语言使用与 SDK 发布日期相匹配的固定 API 版本。对于强类型语言，不要设置其他 API 版本，因为响应对象可能与 SDK 中的强类型不匹配。请改为更新 SDK，使其面向新的 API 版本。

最佳实践

在代码中始终指定集成所针对的 API 版本，而不要依赖账户的默认 API 版本：

// Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-08-26.dahlia'
});

// Avoid: Relying on account default
const stripe = require('stripe')('sk_test_xxx');

Stripe.js 版本管理

详情请参阅 Stripe.js 版本管理。

Stripe.js 采用常青模式，每年发布两次主要版本（Acacia、Basil、Clover、Dahlia）。

加载指定版本的 Stripe.js

通过脚本标签：

<script src="https://js.stripe.com/dahlia/stripe.js"></script>

通过 npm：

npm install @stripe/stripe-js

主要 npm 版本与特定 Stripe.js 版本相对应。

API 版本配对

每个 Stripe.js 版本都会自动与对应的 API 版本配对。例如：

• Dahlia Stripe.js 使用 2026-08-26.dahlia API
• Acacia Stripe.js 使用 2024-12-18.acacia API

无法覆盖此对应关系。

从 v3 迁移

1. 确认代码中当前使用的 API 版本
2. 查看变更日志，了解相关变更
3. 考虑在切换 Stripe.js 版本前逐步更新 API 版本
4. Stripe 将无限期继续支持 v3

移动 SDK 版本管理

详情请参阅 移动 SDK 版本管理。

iOS 和 Android SDK

两个平台都遵循语义化版本控制（MAJOR.MINOR.PATCH）：

• MAJOR：会导致不兼容的 API 变更
• MINOR：新增功能（向后兼容）
• PATCH：错误修复（向后兼容）

新功能和修复仅针对最新的主要版本发布。请定期升级以获取改进。

React Native SDK

采用不同的版本模式（0.x.y 格式）：

• 次要版本变更（x）：包含不兼容变更和新功能
• 补丁更新（y）：仅包含关键错误修复

后端兼容性

除非文档另有说明，所有移动 SDK 都适用于你在后端使用的任何 Stripe API 版本。

升级检查清单

1. 查看 API 变更日志，了解当前版本与目标版本之间的变更
2. 查看 API 升级指南，了解迁移指导
3. 更新服务器端 SDK 软件包版本（例如，npm update stripe、pip install --upgrade stripe）
4. 更新 Stripe 客户端初始化中的 apiVersion 参数
5. 使用 Stripe-Version 标头，根据新 API 版本测试集成
6. 对于接收快照事件的每个目标，检查其配置的 API 版本。对于 webhook 端点，请遵循 webhook 版本管理。对于每个 v2 快照事件目标（包括 webhook 端点、Amazon EventBridge 和 Azure Event Grid 目标），请检查 snapshot_api_version；如果它与目标版本不同，请创建并测试替代目标，因为创建后无法更改此版本。对于替代 webhook 端点，请保存新的签名密钥，并配置处理程序，以便在测试和切换期间同时接受两个密钥。切换完成后，请停用或删除旧目标，以避免重复投递。保持精简事件目标不变
7. 如有需要，更新 Stripe.js 脚本标签或 npm 软件包版本
8. 如有需要，在软件包管理器中更新移动 SDK 版本
9. 将 Stripe 对象 ID 存储在数据库中，并确保数据库支持最多 255 个字符（区分大小写的排序规则）

测试 API 版本变更

使用 Stripe-Version 标头，在不更改默认版本的情况下，根据新版本测试代码：

curl https://api.stripe.com/v1/customers \
  -u sk_test_xxx: \
  -H "Stripe-Version: 2026-08-26.dahlia"

也可以在代码中设置：

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-08-26.dahlia'  // Test with new version
});

重要说明

• 对于受支持的事件类型，请按照迁移指南，从快照事件迁移到精简事件。迁移后，Webhook 负载不再依赖 API 版本升级；用于检索完整事件或相关资源的 API 调用仍按版本区分。
• 您的 Webhook 监听器应妥善处理不熟悉的事件类型
• 升级前，请使用新的版本结构测试 Webhook
• 重大变更会按受影响的产品领域（Payments、Billing、Connect 等）标注
• 多个 API 版本可同时共存，从而支持分阶段采用
• 升级后的 72 小时内，您可以在 Workbench 中回滚到之前的 API 版本