RevenueCat 集成问题排查：当商品为空、权益未解锁…

当用户报告 RevenueCat 行为异常（offerings 为空、商品不加载、购买后权益未激活、Paywall 无法渲染、交易未出现在后台、CustomerInfo 无权益、沙盒购买失败）时，按平台检测、通用代码检查、Dashboard 检查、平台特定排查、验证修复的顺序定位并解决问题。

适用场景

解决思路

1. 检测平台：按顺序检查工作目录并取第一个匹配项——1) React Native：package.json 含 react-native-purchases 或 react-native 依赖，读取 platforms/react-native.md（若同时含 expo 则标记为 Expo 项目）；2) Flutter：项目根目录存在 pubspec.yaml，读取 platforms/flutter.md；3) Kotlin Multiplatform：build.gradle.kts 含 kotlin { … } 多平台 source sets 块或依赖 com.revenuecat.purchases:purchases-kmp*，读取 platforms/kmp.md；4) Android 原生：build.gradle(.kts) 应用 com.android.application 且非 KMP，读取 platforms/android.md；5) iOS 原生：项目根目录存在 Package.swift、*.xcodeproj、*.xcworkspace 或 Podfile，读取 platforms/ios.md。若多个匹配（如 Flutter 项目内的 ios/ 目录），选择拥有构建的最外层项目；仍不明确则询问用户 bug 在哪个平台复现。
2. 执行通用代码侧九项检查清单（按顺序，多数问题在前 5 步解决）：1) 开启 debug 日志并复现——SDK 会叙述其行为，约 80% 的报告仅凭日志即可诊断，各平台文件说明如何将 logLevel 设为 debug；2) 验证 API key 平台与应用匹配——iOS 应用必须使用 appl_… 公钥，Android 应用必须使用 goog_…（Amazon 用 amzn_…），不匹配会在首次网络调用时产生认证错误（iOS 表现为 INVALID_CREDENTIALS，Android 表现为 PurchasesErrorCode.InvalidCredentialsError），用 list-app-public-api-keys MCP 工具列出项目 API key；3) 验证 bundle ID / package name 与 RevenueCat 项目中设置的一致——用 list-apps MCP 工具列出应用，注册的 bundle_id（iOS/App Store）或 package_name（Android/Play Store/Amazon Appstore）必须与构建的应用完全一致（含大小写），不匹配会导致 offerings 返回空；4) 验证 RevenueCat 项目中的 offerings——用 list-offerings MCP 工具并传参 expand=items.package.product，标记 is_current: true 的 offering 必须至少有一个 package，且每个 package 必须引用一个商店商品，零 package 的 offering 即使 getOfferings 成功也会返回空 availablePackages；5) 验证商店商品已上线——商品在 App Store Connect 必须为 "Ready to Submit"，在 Google Play Console 必须为 "Active"，草稿状态商品即使沙盒也不会被商店返回；若日志显示 offerings 从 RevenueCat 到达但商品解析失败，几乎总是此原因；用 get-product-store-state MCP 工具查看 store_status 字段，要修复或更改商店状态（非仅读取）则遵循 revenuecat-store-state 技能；6) 验证测试账号——iOS：设备必须在 设置 → App Store → 沙盒账户 下登录 Sandbox Apple ID（iOS 14+ 在首次沙盒提示后设置）；Android：测试者 Gmail 必须加入 Google Play Console → 设置 → 许可测试，且应用必须通过内部测试 opt-in 链接安装而非侧载；7) 验证网络——企业 VPN、强制门户和某些 DNS 过滤会静默阻断 RevenueCat API 或商店 API，深入排查前先换网络；8) 验证 appUserID——若 logIn(appUserID) 传入的 ID 与用户预期不符，权益会因挂在另一个 RC 用户下而看似缺失，打印 Purchases.shared.appUserID（iOS）/ Purchases.sharedInstance.appUserID（Android）确认匹配；9) 重置并重试——卸载应用、重新登录沙盒/测试账号、从正确渠道重装、重启。
3. 当第 3、4、5 步指向 Dashboard 配置、用户尚无可用应用或需确认修复已生效时，通过 RevenueCat MCP 或 rc CLI 检查 Dashboard。重要：API key 可能可访问多个项目，务必先调用 list-projects；若返回多个项目，询问用户要检查哪个。

适用边界 · 注意事项

• 不适用于非 RevenueCat 的支付/订阅集成问题（如直接使用 StoreKit、Google Play Billing 或其他第三方支付方案）。
• 不适用于纯服务端/后端问题且不涉及 RevenueCat SDK 或 Dashboard 配置的场景。
• 不适用于需要修改商店状态（非仅读取）的场景——那应遵循 revenuecat-store-state 技能。

经验正文