在不花真钱的情况下搭建 RevenueCat…

当你想在开发阶段测试 RevenueCat 购买流程、又不想产生真实扣款时，按平台搭建并验证测试环境。

适用场景

解决思路

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/ 目录），选拥有构建的最外层项目；仍不确定时询问用户要配置哪个平台。
2. 理解各测试通道的保真度与迭代成本：保真度越高，走的真实购买链路越多；保真度越低，迭代越快。
3. RevenueCat Test Store（最低保真度、最快迭代、结果确定）：RevenueCat 托管的合成商店。SDK 用仪表盘上的 test_… API key 配置。购买时弹出 Test Store 对话框，手动选择结果：Successful Purchase、Failed Purchase 或 Cancel。购买会触发权益、更新 CustomerInfo 并出现在仪表盘上，但不会调用 Apple 或 Google。最适合 paywall 迭代、集成测试和 CI 冒烟运行。
4. iOS StoreKit Configuration File（低保真度、Apple 合成）：Xcode 在本地 stub 商店，购买立即成功，无需 App Store Connect 往返。需要 StoreKit 特定行为时有用。此模式下 RevenueCat 交易是否出现在仪表盘取决于 SDK 版本和预期路由，因此不是可靠的仪表盘测试。
5. iOS Sandbox（真实 sandbox Apple ID）/ Android Internal Testing（license tester）：真实商店后端、真实 RevenueCat 仪表盘摄取、真实收据。迭代较慢：构建、安装、等待 Play 传播或 App Store Connect 注册产品。
6. TestFlight（iOS）/ Closed 或 Open Testing（Android）：行为非常接近生产，收据为生产风格，交易落在 RevenueCat 的 production 仪表盘而非 Sandbox 视图。
7. Production：真实扣款，不要用于测试。
8. 从能回答当前问题的最低保真度开始，再逐步上移：UI 和 paywall 迭代放在快速通道；“我的权益是否真的翻转了？”放在 sandbox 或 internal testing。
9. 何时优先用 Test Store 而非 sandbox：RevenueCat Test Store 是按项目在仪表盘配置的合成商店提供方，能产生真实的 RevenueCat 后端记录（CustomerInfo 更新、权益转换、仪表盘交易）而不调用 App Store 或 Google Play。代价是保真度：Test Store 不模拟 Ask to Buy 审批流程、地区特定定价、服务端收据验证细节、商店级审核或拒绝路径，也不模拟完整订阅续订节奏（Test Store 在压缩时钟上最多续订五次）。
10. 在以下情况使用 Test Store：想快速迭代 UI、编写结果确定的集成测试，或运行 CI 检查。任何涉及商店侧行为的测试，都升级到 App Store Sandbox 或 Google Play Internal Testing。
11. Test Store 设置：在仪表盘进入 Apps and providers → Test configuration 区域 → Test Store → Create / Enable。Test Store API key 出现在 Project Settings → API keys 下，带 test_ 前缀。在 debug 构建中用 test key 配置 SDK，在 release 构建中用生产 key（appl_… / goog_…）。各平台文件展示了按平台的 key 切换模式。
12. Test Store key 绝不能发布到生产：用构建配置把 key 隔离，确保 release 二进制无法走 Test Store。
13. Sandbox 交易在仪表盘上单独显示：RevenueCat 仪表盘有 Sandbox 与 Production 视图切换。Sandbox 购买只出现在 Sandbox 下。若测试交易未出现在那里，说明 SDK 没有上报（检查 API key、configure 调用和网络），或该购买走的是不触达 RevenueCat 后端的 StoreKit config file。
14. Sandbox 中的加速续订：sandbox 中订阅续订按加速测试时钟运行，可在几分钟而非几周内验证续订逻辑。iOS sandbox 续订节奏（按 Apple 文档）：daily → 每 3 分钟，weekly → 每 3 分钟，monthly → 每 5 分钟，2 months → 每 10 分钟，3 months → 每 15 分钟，6 months → 每 30 分钟，yearly → 每小时。订阅最多自动续订 6 次后过期。Android sandbox 续订节奏见 Google Play Console → Subscriptions testing，license tester 订阅按同样的加速时钟续订。
15. 首次购买流程使用全新的测试用户：购买历史绑定在测试账号（sandbox Apple ID 或 license tester Gmail）上并会持久保留。用已使用过首次优惠或免费试用的账号测试“首次购买”逻辑、介绍性优惠或免费试用，会得到误导性结果。为干净的首购场景创建新的 sandbox tester。
16. 以仪表盘而非设备为准进行确认：设备上购买成功不等于 RevenueCat 已记录。始终确认：1) 交易出现在 RevenueCat 仪表盘（Sandbox 视图）；2) 预期的 appUserID 拥有该交易；3) 该用户上预期权益已激活。若设备显示成功但仪表盘没有，问题在配置路径而非商店。
17. 实现：读取与检测结果匹配的平台文件：platforms/ios.md、platforms/android.md、platforms/kmp.md、platforms/flutter.md、platforms/react-native.md。
18. 验证：测试环境搭建完成的判定标准：1) 测试用户的一次测试购买端到端成功；2) 交易出现在 RevenueCat 仪表盘 Sandbox 视图，并归属于你登录所用的 appUserID；3) 购买完成后 customerInfo 上预期权益已激活；4) 在全新安装的应用上恢复购买，能把权益恢复到同一测试用户。若这四步中任何一步失败，环境就未就绪；revenuecat-troubleshoot 技能覆盖常见根因。

适用边界 · 注意事项

• 需要测试商店侧行为（如 Ask to Buy 审批、地区定价、服务端收据验证、审核/拒绝路径、完整续订节奏）时，不要用 Test Store，应升级到 App Store Sandbox 或 Google Play Internal Testing。
• 不要把 Test Store 的 test_ key 发布到生产环境。
• 不要用 Production 通道做测试（会产生真实扣款）。