revenuecat-troubleshoot

revenuecat-troubleshoot：诊断 RevenueCat 集成问题

当用户报告 RevenueCat 的行为与预期不符时，请使用此技能：商品方案为空、缺少产品、成功购买后权益仍未解锁、付费墙无法呈现，或沙盒交易始终未显示在仪表板中。

此技能结合了两个方面：

1. 代码侧诊断 — 开启调试日志，逐项检查通用清单，再深入平台特定内容。
2. 仪表板检查 — 使用 RevenueCat MCP 服务或 rc CLI（参见 revenuecat-cli 技能）读取项目、应用、产品、权益、商品方案和 Webhook，并提出修复建议。

请按顺序执行。大多数问题在深入平台特定内容之前就能解决。

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 { … } 多平台源集代码块，或依赖 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/ 文件夹），请选择最外层的项目，也就是负责构建的项目。如果仍无法确定，请询问用户问题在哪个平台上复现。

2. 通用代码侧检查清单

按顺序检查以下九项。大多数问题都能通过第 1 至第 5 步解决。

1. 启用调试日志并重现问题。 SDK 会记录其执行过程。大约 80% 的问题仅凭日志输出就能诊断。每个平台的文件都展示了如何将 logLevel 设为 debug。
2. 确认 API 密钥的平台与应用匹配。 iOS 应用必须使用 appl_… 公共 SDK 密钥。Android 应用必须使用 goog_…（Amazon 应用使用 amzn_…）。密钥不匹配会导致首次网络调用时出现身份验证错误。在 iOS 上，这会显示为 INVALID_CREDENTIALS 错误代码；在 Android 上，则会显示为 PurchasesErrorCode.InvalidCredentialsError。使用 list-app-public-api-keys RevenueCat MCP 工具列出项目的 API 密钥。
3. 确认 Bundle ID／软件包名称与 RevenueCat 项目中的设置一致。 使用 list-apps RevenueCat MCP 工具列出应用。其中注册的 bundle_id（iOS／App Store）或 package_name（Android／Play Store／Amazon Appstore）必须与构建的应用完全一致，包括大小写。不匹配会导致返回的 offerings 为空，因为应用无法被识别。
4. 确认 RevenueCat 项目中的 offerings。 使用 list-offerings RevenueCat MCP 工具列出项目的 offerings，并传入 limit: 100 和 expand=items.package.product。默认的 20 条分页可能会漏掉当前 offering，而部分分页看起来与项目没有当前 offering 的情况相同。标记为 is_current: true 的 offering 必须至少关联一个 package，且每个 package 都必须引用一个商店产品。即使 getOfferings 成功，零 package 的 offering 也会返回空的 availablePackages 列表。
5. 确认商店产品已上线。 产品必须在 App Store Connect 中处于“Ready to Submit”状态，或在 Google Play Console 中处于“Active”状态。草稿状态的产品不会由商店返回，即使是在沙盒环境中。如果 SDK 日志显示 offerings 已从 RevenueCat 返回，但产品无法解析，几乎总是这个原因。使用 get-product-store-state RevenueCat MCP 工具查看产品在 App Store Connect 或 Google Play Console 中的状态（字段 store_status）。如需修复或更改商店状态（而不只是查看状态），请遵循 revenuecat-store-state 技能。
6. 确认测试账户。 iOS：设备必须在“设置” →“App Store” →“沙盒账户”中登录 Sandbox Apple ID（iOS 14+ 上，在首次显示沙盒提示后设置）。Android：测试人员的 Gmail 必须添加到 Google Play Console →“设置” →“许可测试”，并且应用必须通过 Play 测试渠道的加入测试链接安装，不能通过侧载安装（具体使用哪个渠道，请参阅下方的 Android 检查清单）。
7. 确认网络状况。 企业 VPN、强制门户和某些 DNS 过滤器可能会悄悄拦截 RevenueCat API 或商店 API。深入排查前，先尝试更换网络。
8. 确认 appUserID。 如果调用 logIn(appUserID) 时传入的 ID 与用户预期不符，权益就会显示为缺失，因为它们关联到了另一个 RC 用户。打印 Purchases.shared.appUserID（iOS）／Purchases.sharedInstance.appUserID（Android），并确认其匹配。
9. 重置并重试。 卸载应用，重新登录沙盒／测试账户，从正确的渠道重新安装，然后重新启动应用。

3. 通过 RevenueCat MCP 或 rc CLI 检查仪表板

如果上述第 3、4 或第 5 步指向仪表板配置问题、用户还没有可用的应用，或你需要确认修复已生效，请使用此方法。

重要： API 密钥可能有权访问多个项目。请始终先调用 list-projects。如果返回了多个项目，请询问用户要检查哪个项目。

阶段 A：收集上下文

1. 症状 — “具体哪里无法正常工作？你看到了哪些错误消息？使用的是哪个平台（iOS、Android、Web）？”
2. 用户状态 — “新购买的用户还是现有订阅用户遇到了这个问题？使用的是沙盒环境还是生产环境？”

阶段 B：系统性诊断

通过 MCP 工具或其 rc CLI 等效命令，按此清单逐项排查（参见 revenuecat-cli 技能）。每个 list-* 工具都对应 rc <noun> list（例如，list-offerings → rc offerings list，list-apps → rc apps list）；list-app-public-api-keys 对应 rc apps keys <app-id>；get-product-store-state 对应 rc products show <product-id> --store-state。

检查 1：项目概览

list-projects → ask user to select project if multiple
list-apps (with selected project_id)

• 确认项目存在且已添加应用。

检查 2：产品

list-products
get-product-store-state

• 每个商店商品都存在对应产品。
• 商店标识符与 App Store Connect / Play Console 中的内容完全一致。
• 产品类型正确（订阅或一次性购买）。
• Play Store：订阅使用 product_id:base_plan_id 格式；一次性购买仅使用 product_id。
• 商店状态：store_status.status = ok。

list-products 返回的时长为 null，并不意味着产品配置有误（也可能只是尚未购买过）。请根据 get-product-store-state 判断商店配置。

检查 3：权益

list-entitlements
get-products-from-entitlement (for each entitlement)

• 每个访问级别都存在对应权益。
• 产品已关联到权益。
• 没有孤立产品（未授予任何权益的产品）。

检查 4：Offerings

list-offerings (limit: 100)
list-packages (for the offering with is_current: true)

• 至少有一个 offering 的 is_current: true。
• Package 中包含产品。
• Package 标识符遵循标准惯例（$rc_monthly 等）。

检查 5：Webhook（如果怀疑是服务端问题）

list-webhook-integrations

• Webhook URL 正确且可访问。
• 环境匹配（生产环境或沙盒环境）。

检查 6：SDK 兼容性（如果 SDK 门控的功能表现异常）

Paywall 组件、实验分配、曝光跟踪、Customer Center 行为、In-App Currencies 和 offering 功能都依赖最低 SDK 版本。在声明任何 SDK 版本信息之前，请先加载 revenuecat-sdk-compatibility 技能。

• 已通过 list-sdk-feature-gates 检查该功能的门控条件。
• 已通过 list-sdk-versions 检查有关项目 SDK 采用情况的任何说法。
• 报告明确区分所需 SDK 版本与项目中观察到的版本。

阶段 C：报告并提供修复方案

Diagnostic Report
=================
Project: {project_name}

Checks Passed: ✅
  - Project exists and is accessible
  - 2 apps configured (iOS, Android)
  - 4 products found

Issues Found: ⚠️

1. CRITICAL: Product not attached to entitlement
   Product: annual_premium (prod123)
   Fix: Attach this product to an entitlement

2. WARNING: Offering has empty package
   Offering: default / Package: $rc_annual has no products
   Fix: Attach annual_premium to this package

3. INFO: No webhook configured
   Optional but recommended for server-side access control

Recommended Actions:
1. Attach annual_premium to "premium" entitlement
2. Attach annual_premium to $rc_annual package

Would you like me to fix issues #1 and #2 now?

对于每个可修复的问题，请先征得用户同意，然后通过 MCP 执行：

• attach-products-to-entitlement
• attach-products-to-package

4. 平台特定步骤

根据检测结果，阅读对应平台的文件。每个文件都会列出上述内容未涵盖的平台特定注意事项（StoreKit 配置文件、Gradle/desugaring、Metro 缓存、Expo prebuild 等）。

• platforms/ios.md
• platforms/android.md
• platforms/kmp.md
• platforms/flutter.md
• platforms/react-native.md

5. 验证修复

在满足以下条件之前，不要宣称问题已修复：

1. 之前显示错误的日志现在显示预期的成功信息（已返回至少包含一个 package 的 offerings、购买已完成、权益已激活）。
2. 控制面板反映了此次更改。对于购买，请检查 Customers 页面的 Sandbox 视图，并确认交易已关联到正确的 appUserID。
3. 原始报告中的复现步骤现在可以通过。

如果用户无法在本地复现，请让他们发送从应用启动到故障发生时刻的完整调试日志。SDK 自身的输出通常就足够了。

---

参考：SDK 错误代码

常见错误

错误代码	可能原因	解决方案
INVALID_APP_USER_ID	包含保留字符或为空字符串	仅使用字母数字字符、下划线和连字符作为 ID
INVALID_CREDENTIALS	API 密钥错误或 Bundle ID 不匹配	确认 API 密钥与应用匹配
NETWORK_ERROR	网络未连接或防火墙限制	检查网络，并确认已允许访问 RevenueCat 域名
STORE_PROBLEM	商店停机、配置问题或 iOS 18.x 错误	检查商店状态并确认配置，参见下方的已知 iOS 问题
SIGNATURE_VERIFICATION_FAILED	收据被篡改或配置错误	确认 In-App Purchase Key（iOS）或服务凭据

购买错误

错误代码	解决方案
RECEIPT_ALREADY_IN_USE	调用 restorePurchases() 或同步客户
PRODUCT_NOT_AVAILABLE_FOR_PURCHASE	在 App Store Connect / Play Console 中确认产品状态
PURCHASE_NOT_ALLOWED	检查家长控制和付款方式
PRODUCT_ALREADY_PURCHASED	调用 restorePurchases() 进行同步

参考：调试日志解读

请开发者启用调试日志：

• iOS：Purchases.logLevel = .debug
• Android：Purchases.logLevel = LogLevel.DEBUG

日志表情符号指示：🍎 Apple/StoreKit · 🤖 Google Play · 📦 Amazon · 😿 RevenueCat 后端。

参考：已知平台问题

iOS

iOS 18.0–18.3.2：StoreKit Daemon 连接失败

• 症状：在实体设备上，约 25% 的购买会出现 STORE_PROBLEM（NSCocoaErrorDomain Code 4097）。
• 修复方法：升级到 iOS 18.4+。

iOS 18.4–18.5 模拟器：产品无法加载

• 症状：在使用沙盒的模拟器中，产品返回空结果。
• 受影响范围：仅模拟器——实体设备和生产环境不受影响。
• 修复方法：在实体设备上测试，或使用搭载 iOS 26+ 模拟器的 Xcode 26+。

Android

ProxyBillingActivity NullPointerException

• 通常由自动化测试或 Play 商店预发布报告触发，涉及 LG Nexus 5X / 已 root 设备。
• 可在崩溃报告工具中安全地忽略或屏蔽。

NoCoreLibraryDesugaringException / NoClassDefFoundError

• 修复方法：在 build.gradle 中启用核心库脱糖，或提高 minSdk。

参考：平台配置检查清单

iOS

• 在 App Store Connect 中签署 Paid Applications 协议，填写完整银行信息，并确保协议尚未过期（检查其状态；更改最长需要 24h 才会生效）。
• Apple Developer Program 会员资格有效，并已设置有效的付款方式和自动续订。
• 已将 In-App Purchase Key 上传到 RevenueCat（StoreKit 2 / SDK 5.x+）。
• 也已将 App-Specific Shared Secret 添加到 RevenueCat；缺少任一凭据都可能导致产品和优惠无法加载。
• 产品状态显示为“Ready to Submit”或“Approved”。
• Xcode、App Store Connect 和 RevenueCat 中的 Bundle ID 完全一致。
• 对于新产品：等待 24h 以使更改生效。

Android

• 应用已发布到至少封闭测试轨道（内部测试不可用）。
• 已在 Play Console 中将测试账号添加为许可测试人员。
• 已将具有 Finance 权限的服务账号凭据（JSON）上传到 RevenueCat。
• 订阅使用 product_id:base_plan_id 格式；一次性商品仅使用 product_id。
• 新商品：等待 24 小时以完成同步。

参考：App Store 审核被拒问题排查

“获取商品时出错” — 首次提交时，商品必须与应用一同提交审核。在 App Store Connect 中创建商品，然后同时提交应用和商品。

“购买过程中出错”（Sandbox） — Apple Sandbox 服务中断。告知审核人员，提供 RevenueCat Sandbox 面板的截图，证明测试购买正常，并请其重试。

“购买后内容未解锁” — 在 RevenueCat 中检查商品与权益的关联。确保应用在购买后调用 getCustomerInfo()。

参考：常见问题

用户已购买但没有权益 — 检查商品与权益的关联，并确认商店标识符完全一致。

Offerings 返回为空 — 确认存在 current offering、套餐已关联商品，且应用商店中存在这些商品。

Webhook 未收到事件 — 确认 URL 可通过互联网访问且返回 200 OK。使用 webhook.site 进行测试。

订阅状态不同步 — SDK 会缓存 CustomerInfo 5 分钟（前台状态）。强制刷新：

// iOS
Purchases.shared.getCustomerInfo(fetchPolicy: .fetchCurrent) { ... }

// Android
Purchases.sharedInstance.getCustomerInfoWith(CacheFetchPolicy.FETCH_CURRENT) { ... }

SDK 启动时崩溃（iOS / Xcode 26） — 在其他网络库之前初始化 RevenueCat。

SDK 启动时崩溃（Android） — 启用核心库 desugaring，或将 minSdk 提高到 24+。