用途
upgrade-stripe 是 Stripe 官方发布的技能指南，用于指导开发者升级 Stripe 相关组件的版本，涵盖 Stripe API 版本、Webhook 端点、服务端 SDK、Stripe.js 以及移动端 SDK。该技能旨在帮助使用 Stripe 的开发团队在版本升级过程中识别兼容性变化、执行迁移步骤并完成验证。
主要能力
API 版本选择与比较
技能指导用户确定目标 API 版本：如果用户指定了目标版本则直接使用，否则可通过 Stripe CLI 的 stripe docs /api/versioning 等文档或工具查询 docs.stripe.com 上的当前版本。API 版本采用基于日期的格式（如 2026-09-30.endive、2025-08-27.basil），新稳定版本每月发布。技能提供一个内置的备用版本 2026-09-30.endive，仅在无法访问 docs.stripe.com 时使用。在变更前，技能会指导对比目标版本与集成中固定的每个 API 版本，包括客户端配置、逐请求覆盖和 Webhook 端点。
变更类型识别
技能区分两类变更：向后兼容变更（无需代码更新，如新增 API 资源、新增可选请求参数、已有响应中的新属性、不透明字符串长度变化、新增 Webhook 事件类型）和破坏性变更（需要代码更新，如字段重命名或移除、行为修改、端点或参数移除）。从 2024-09-30.acacia 发布开始，Stripe 每月发布新的 API 版本且不含破坏性变更；每年两次的新主版本（如 Basil）则包含破坏性变更。
服务端 SDK 版本管理
技能区分两类 SDK 的版本管理方式：动态类型语言（Ruby、Python、PHP、Node.js）支持全局配置和逐请求覆盖 API 版本；强类型语言（Java、Go、.NET）使用与 SDK 发布版本绑定的固定 API 版本，应通过更新 SDK 来定位新 API 版本，而非覆盖 SDK 固定的版本。技能还提供了在代码中显式指定 API 版本的最佳实践示例。
Stripe.js 版本管理
Stripe.js 采用常青模型，每半年发布一次主版本（Acacia、Basil、Clover、Dahlia、Endive）。技能说明了通过 script 标签和 npm 加载版本化 Stripe.js 的方式，以及每个 Stripe.js 版本自动配对对应 API 版本的机制（如 Endive Stripe.js 使用 2026-09-30.endive API），该配对关系不可覆盖。
移动端 SDK 版本管理
iOS 和 Android SDK 遵循语义化版本（MAJOR.MINOR.PATCH）；React Native SDK 使用 0.x.y 模式。所有移动端 SDK 可与后端使用的任意 Stripe API 版本配合工作，除非文档另有说明。
升级检查清单
技能提供了完整的升级检查清单，包括：审查 API 变更日志、查看 API 升级指南、更新服务端 SDK 包版本、更新 Stripe 客户端初始化中的 apiVersion 参数、使用 Stripe-Version 头测试集成、审查每个接收快照事件的目标配置的 API 版本、更新 Stripe.js 和移动端 SDK 版本、确保数据库中存储 Stripe 对象 ID 的字段支持最多 255 字符等。
版本切换测试
技能说明如何使用 Stripe-Version 请求头在不更改默认版本的情况下测试代码对新版本的兼容性，并提供了 curl 和代码示例。
Webhook 版本处理
技能区分快照事件与精简事件：精简事件载荷无版本，无需在 API 版本变更时升级；检索完整事件或相关资源的 API 调用仍受版本控制。对于 v2 快照事件目标（包括 Webhook 端点、Amazon EventBridge、Azure Event Grid），需检查 snapshot_api_version，若与目标不同则创建并测试替代目标，因为创建后无法更改。
使用方式
该技能以指南形式供开发者或 AI 编码助手在升级 Stripe 版本时参考。使用步骤包括：确定目标 API 版本、对比当前固定版本、识别变更类型、更新 SDK 和初始化配置、通过 Stripe-Version 头测试、更新 Webhook 端点、更新前端和移动端 SDK、存储对象 ID 时确保字段长度。升级后 72 小时内可在 Workbench 中回滚到之前的 API 版本。
适用场景
适用于需要升级 Stripe API 版本、Webhook 端点、服务端 SDK、Stripe.js 或移动端 SDK 的开发团队，尤其适合使用多种语言 SDK 和前端 Stripe.js 的复杂集成场景。
限制
该技能为升级指南性质，未提供具体的收费或价格信息（暂未提供）。强类型语言 SDK 不可覆盖 API 版本。Stripe.js 与 API 版本的配对关系不可覆盖。v2 快照事件目标创建后无法更改其 API 版本，需创建替代目标。备用 API 版本仅为快照，可能已过时，应仅在无法访问官方文档时使用。