upgrade-stripe

升级 Stripe 版本

选择目标 API 版本

如果用户指定了目标 API 版本，请使用该版本。否则，请使用任何可用的文档或网页工具，在 docs.stripe.com 上查找当前版本，例如使用 Stripe CLI 执行 stripe docs /api/versioning。API versioning 页面会在以“The current version is”开头的句子中注明当前版本。

捆绑的备用 API 版本：2026-09-30.endive。此值仅是此技能上次生成时（2026-10-14）的快照。版本标识符以 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 versioning。

了解 Stripe API 版本控制

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

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

变更类型

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

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

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

• 字段重命名或移除
• 行为变更
• 端点或参数移除

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

服务端 SDK 版本控制

有关如何在代码中设置 API 版本的详情，请参阅 Set a Stripe API version for your SDK。

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

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

全局配置：

import stripe
stripe.api_version = '2026-09-30.endive'

Stripe.api_version = '2026-09-30.endive'

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-09-30.endive'
});

每次请求覆盖：

stripe.Customer.create(
  email="[email protected]",
  stripe_version='2026-09-30.endive'
)

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

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

最佳实践

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

// Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-09-30.endive'
});

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

Stripe.js 版本管理

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

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

加载指定版本的 Stripe.js

通过 Script Tag：

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

通过 npm：

npm install @stripe/stripe-js

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

API 版本配对

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

• Endive Stripe.js 使用 2026-09-30.endive 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 端点，请保存新的签名密钥，并配置处理程序在测试和切换期间同时接受两个密钥。切换完成后，请停用或删除旧目标，以避免重复投递。保持 thin event 目标不变
7. 如有需要，更新 Stripe.js Script Tag 或 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-09-30.endive"

也可以在代码中指定：

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-09-30.endive'  // Test with new version
});

重要说明

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