upgrade-stripe 是用于指导升级 Stripe API 版本与 SDK 的技能，来源于 stripe/com。其核心用途是帮助开发者把集成升级到新的 Stripe API 版本，并同步更新服务端 SDK、Stripe.js 与移动端 SDK。本技能指出，当前最新的 Stripe API 版本为 2026-08-26.dahlia，除非用户指定其它目标版本，否则升级时应使用该版本。
关于版本机制：Stripe 使用基于日期的 API 版本（例如 2026-08-26.dahlia、2025-08-27.basil、2024-12-18.acacia），账号的 API 版本决定请求与响应行为。变更分为两类：向后兼容变更无需修改代码，包括新增 API 资源、新增可选请求参数、既有响应中新增属性、不透明字符串长度变化（如对象 ID）、新增 webhook 事件类型；破坏性变更需要修改代码，包括字段重命名或移除、行为修改、移除端点或参数。应查阅 API Changelog 了解版本之间的全部变更。
服务端 SDK 版本管理：动态类型语言（Ruby、Python、PHP、Node.js）提供灵活的版本控制，可做全局配置（如 Python 的 stripe.api_version = '2026-08-26.dahlia'、Node.js 初始化时的 apiVersion 选项），也可按请求覆盖（如在创建 Customer 时传 stripe_version）。强类型语言（Java、Go、.NET）使用与 SDK 发布日对应的固定 API 版本，不应为其设置不同的 API 版本，因为响应对象可能与 SDK 的强类型不匹配，应改为更新 SDK 以切换到新的 API 版本。最佳实践是在代码中始终显式指定所集成的 API 版本，而不要依赖账号的默认 API 版本。
Stripe.js 版本管理：Stripe.js 采用常青模型，每半年发布一次主版本（Acacia、Basil、Clover、Dahlia）。可通过 script 标签加载带版本的 Stripe.js（例如 https://js.stripe.com/dahlia/stripe.js），或通过 npm 安装 @stripe/stripe-js，npm 主版本对应特定的 Stripe.js 版本。每个 Stripe.js 版本会自动配对相应的 API 版本，例如 Dahlia Stripe.js 使用 2026-08-26.dahlia API，Acacia Stripe.js 使用 2024-12-18.acacia API，此关联无法覆盖。从 v3 迁移的步骤为：在代码中确认当前 API 版本、查阅 changelog 中的相关变更、考虑在切换 Stripe.js 版本前先逐步更新 API 版本；Stripe 会无限期继续支持 v3。
移动端 SDK 版本管理：iOS 与 Android SDK 均遵循语义化版本（MAJOR.MINOR.PATCH），MAJOR 为破坏性 API 变更，MINOR 为向后兼容的新功能，PATCH 为向后兼容的错误修复；新功能与修复仅在最新主版本上发布，应定期升级以获取改进。React Native SDK 采用不同模型（0.x.y）：次版本变更（x）同时包含破坏性变更与新功能，补丁更新（y）仅包含关键错误修复。除非文档另有说明，所有移动端 SDK 均可与后端使用的任意 Stripe API 版本配合工作。
升级检查清单包括：查阅 API Changelog 了解当前版本与目标版本之间的变更；查看 Upgrades Guide 获取迁移指导；更新服务端 SDK 包版本（如 npm update stripe、pip install --upgrade stripe）；更新 Stripe 客户端初始化中的 apiVersion 参数；使用 Stripe-Version 头针对新 API 版本测试集成；更新 webhook 处理器以处理新的事件结构；如有需要更新 Stripe.js 的 script 标签或 npm 包版本；如有需要更新包管理器中的移动端 SDK 版本；在数据库中存储 Stripe 对象 ID 时预留最多 255 个字符（区分大小写的排序规则）。
测试 API 版本变更：可使用 Stripe-Version 头在不更改默认版本的情况下用新版本测试代码，例如通过 curl 请求 https://api.stripe.com/v1/customers 并带上 -H "Stripe-Version: 2026-08-26.dahlia"，或在代码中把 apiVersion 设为新版本进行测试。重要注意事项：webhook 监听器应能优雅处理不熟悉的事件类型；升级前先用新版本结构测试 webhook；破坏性变更会按受影响的产品领域（Payments、Billing、Connect 等）打标签；多个 API 版本可同时共存，支持分阶段采用。