Name: upgrade-stripe
Author: stripe

最新的 Stripe API 版本是 2026-06-24.dahlia - 除非用户指定了不同的目标版本，否则升级时请使用此版本。

升级 Stripe 版本

本指南涵盖 Stripe API 版本、服务器端 SDK、Stripe.js 和移动端 SDK 的升级。

了解 Stripe API 版本控制

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

变更类型

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

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

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

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

请查看 API 变更日志了解版本间的所有变更。

服务器端 SDK 版本控制

详情请参阅 SDK 版本管理。

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

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

全局配置：

import stripe
stripe.api_version = '2026-06-24.dahlia'

Stripe.api_version = '2026-06-24.dahlia'

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

每次请求覆盖：

stripe.Customer.create(
  email="customer@example.com",
  stripe_version='2026-06-24.dahlia'
)

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

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

最佳实践

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

// 好：显式版本
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-06-24.dahlia'
});

// 避免：依赖账户默认
const stripe = require('stripe')('sk_test_xxx');

Stripe.js 版本控制

详情请参阅 Stripe.js 版本控制。

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

加载版本化的 Stripe.js

通过 Script 标签：

<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-06-24.dahlia API
Acacia Stripe.js 使用 2024-12-18.acacia API

您无法覆盖此关联。

从 v3 迁移

确定代码中的当前 API 版本
查看变更日志了解相关变更
考虑在切换 Stripe.js 版本之前逐步更新 API 版本
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 版本一起使用。

升级检查清单

查看 API 变更日志了解当前版本与目标版本之间的变更
查看升级指南获取迁移指导
更新服务器端 SDK 包版本（例如 npm update stripe、pip install --upgrade stripe）
更新 Stripe 客户端初始化中的 apiVersion 参数
使用 Stripe-Version 标头测试您的集成是否适用于新的 API 版本
更新 Webhook 处理程序以处理新的事件结构
根据需要更新 Stripe.js 脚本标签或 npm 包版本
根据需要更新包管理器中的移动端 SDK 版本
在支持最多 255 个字符（区分大小写的排序规则）的数据库中存储 Stripe 对象 ID

测试 API 版本变更

使用 Stripe-Version 标头测试您的代码是否适用于新版本，而无需更改默认版本：

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

或者在代码中：

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-06-24.dahlia'  // 使用新版本测试
});

重要说明

您的 Webhook 监听器应优雅地处理不熟悉的事件类型
在升级前使用新版本结构测试 Webhook
破坏性变更会按受影响的产品领域（支付、计费、Connect 等）进行标记
多个 API 版本可以同时共存，从而实现分阶段采用

upgrade-stripe

相关 Skills