前言¶
Stripe 在 2024 年起採用按月發佈的 API 版本命名（如 2026-09-30.endive），服務端 SDK、Stripe.js、移動端 SDK 與 Webhook 各自有版本規則，且強類型語言 SDK 與動態語言在「能否覆蓋 API 版本」上行爲不同。升級時若只改 npm 包版本、不覈對賬戶與 Webhook 上的 pin，或誤把 thin event 與 snapshot event 一併升級，容易在測試環境通過、生產環境因簽名或字段變更失敗。下面介紹 Stripe 官方倉庫中的 Agent Skill upgrade-stripe，用於在編碼助手場景下按文檔順序完成版本選擇與破壞性變更排查。
這是什麼¶
upgrade-stripe 是 Stripe 在 stripe/ai 倉庫中維護的 Agent Skill（SKILL.md 格式）。官方描述爲：指導升級 Stripe API 版本、Webhook 端點、服務端 SDK、Stripe.js 與移動端 SDK。
它解決的是「文檔分散、多組件聯動」的問題：同一集成裏可能同時存在客戶端 apiVersion、按請求覆蓋、Webhook / Event Destination 的 snapshot API 版本，以及 Java / Go / .NET 與 Ruby / Python / Node 不同的版本策略。Skill 把選型、對照 changelog、改配置與測試的順序寫進可被 Agent 執行的流程，而不是替代 API versioning、API upgrades 與 API changelog 原文。
核心功能¶
以下能力均來自官方 SKILL.md 與 officialskills.sh 說明。
選定目標 API 版本¶
- 若用戶已指定目標版本，以用戶指定爲準。
- 否則應通過可用文檔或工具查詢當前版本，例如 Stripe CLI 的
stripe docs /api/versioning，或在 API versioning 頁面查找以 “The current version is” 開頭的句子。 - Skill 內 bundled 回退版本爲
2026-09-30.endive（生成快照日期爲 2026-10-19）；僅在無法訪問 docs.stripe.com 時使用，且超過約一個月未更新時可能已過時，不得猜測更新的版本號。
變更前需將目標版本與集成中所有 pin 對比：客戶端配置、按請求覆蓋、Webhook 端點。除非用戶明確要求，不得把 pin 降到更舊版本，也不得把穩定 pin 改爲 preview。已匹配目標的 pin 應報告爲未變更。須說明所選目標及來源；若無法在線覈實，應標明最新版本未驗證，不得聲稱集成已處於最新版。
Webhook 與事件目的地¶
審查時需區分 snapshot events 與 thin events。Thin event 載荷未綁定 API 版本，變更賬戶 API 版本時無需升級對應目的地。通過 API 拉取完整 event 或關聯資源時仍受 API 版本約束。
對 v2 snapshot 類目的地（含 Webhook、Amazon EventBridge、Azure Event Grid），需檢查 snapshot_api_version；若與目標不一致，因創建後不可修改，應新建並測試替代目的地。替換 Webhook 時需保存新 signing secret，並在切換期間讓處理器同時接受新舊 secret；切換完成後禁用或刪除舊目的地以避免重複投遞。Thin event 目的地保持不變。
服務端 SDK¶
- 動態類型語言（Ruby、Python、PHP、Node.js）：可在全局配置或單次請求中設置 API 版本；curl 測試時使用
Stripe-Version頭，示例中的 bundled 版本應替換爲所選目標。 - 強類型語言（Java、Go、.NET）：SDK 發佈與固定 API 版本綁定，不應在代碼中強行覆蓋爲與 SDK 不符的版本；應選用面向目標 API 版本的 SDK 發佈。Preview 目標需各語言對應的
betaSDK，見 SDK versioning。
最佳實踐是在代碼中顯式聲明集成的 API 版本，而非僅依賴賬戶默認版本。
Stripe.js 與移動端¶
- Stripe.js 採用 evergreen 模型，大版本（如 Acacia、Basil、Endive）約每半年發佈；腳本加載示例爲
https://js.stripe.com/endive/stripe.js，npm 包@stripe/stripe-js的大版本與 Stripe.js 大版本對應。每個 Stripe.js 大版本與固定 API 版本配對（例如 Endive 對應2026-09-30.endive），不可覆蓋該關聯。從 v3 遷移時官方建議先識別當前 API 版本、查閱 changelog，再考慮在切換 Stripe.js 大版本前逐步提升 API 版本；v3 仍長期支持。 - iOS / Android SDK 使用語義化版本（MAJOR.MINOR.PATCH）；React Native SDK 使用 0.x.y，minor 可能含破壞性變更。移動端 SDK 在文檔未另行說明時，可與後端任意 API 版本配合。
升級檢查清單（摘要）¶
官方清單包括：查閱 changelog 與 upgrades 指南；升級服務端 SDK 包；更新客戶端 apiVersion；用 Stripe-Version 頭對新版本做集成測試；按上文處理 snapshot 類 Webhook / Event Destination；按需更新 Stripe.js 與移動端 SDK 等。完整步驟見 Skill 原文。
安裝與啓用¶
在支持 Agent Skills 的環境中，可通過官方列出的命令安裝整個 stripe/ai 倉庫中的單個 skill：
npx skills add https://github.com/stripe/ai --skill upgrade-stripe
也可將 Skill 目錄鏈接交給編碼助手安裝：https://github.com/stripe/ai/tree/main/skills/upgrade-stripe。
資料中未區分 Cursor、Codex CLI、Claude Code 的安裝差異；以各產品對 npx skills add 或 SKILL.md 路徑的支持爲準。
典型用法¶
下列場景來自 officialskills.sh 的 “When to use it” 說明，與 Skill 能力一致：
- 將 Node.js 應用 pin 到指定 Stripe API 版本（例如
2026-02-25.clover）。 - 在正式切換前，用
Stripe-Version請求頭對新 API 版本做試探性調用。 - 事件結構發生破壞性變更後，遷移 Webhook 處理器（含新建 snapshot 目的地與雙 secret 過渡）。
- 僅升級 Python 後端的 Stripe SDK 包，並覈對是否需同步修改
api_version配置。 - 結賬頁從 Stripe.js v3 切換到某一新大版本（如 Clover）時，對照 changelog 與 API / Stripe.js 配對關係。
動態語言顯式指定版本的寫法（示例中的版本號應替換爲你的目標版本）：
import stripe
stripe.api_version = '2026-09-30.endive'
const stripe = require('stripe')('sk_test_xxx', {
apiVersion: '2026-09-30.endive'
});
適用場景與注意¶
適合：維護 Stripe 集成的後端或全棧開發者；需要在一次對話裏系統梳理 API 版本、SDK、Stripe.js、Webhook snapshot 版本與測試順序的團隊；2026 年前後頻繁跟進 Stripe 月度 API 與半年度大版本變更時，用 Skill 約束 Agent 不猜測版本號、不降級 pin。
注意：
- Skill 不能替代閱讀 API changelog；破壞性變更仍需人工判斷業務代碼影響。
- bundled 回退版本
2026-09-30.endive僅爲離線快照，生產選型應以 docs.stripe.com 或 CLI 查詢結果爲準。 - 強類型 SDK 與 preview / beta 版本有額外約束，需按官方 SDK versioning 選包，不宜只改 HTTP 頭。
- Webhook snapshot 目的地創建後不可改
snapshot_api_version，計劃升級時應預留新建端點與簽名密鑰輪換窗口。
結尾¶
upgrade-stripe 把 Stripe 多組件版本模型與官方升級清單編碼爲 Agent 可遵循的流程，適合在升級 SDK 或 API 大版本時減少漏改 Webhook pin 或誤升級 thin event 的風險。官方 Skill 地址：https://github.com/stripe/ai/tree/main/skills/upgrade-stripe。
