iOS 17.4 内购适配避坑：StoreKit 2 事务流与恢复购买实战

如果你的应用在用户设备上出现“购买成功但权益没到账”、“恢复购买无限转圈”、“订阅状态突然丢失”这类问题，而你第一反应是去查网络请求、查服务端日志，那可能查错了方向。这段时间我在给某应用做 iOS 17.4 适配时，反复被 StoreKit 的错误码拉回现场，整整花了一周才把问题理干净。这篇文章把我在 iOS 17.4 的 StoreKit 上踩到的坑、定位思路和最终落地方案整理出来，主要内容包括交易流重复回调、恢复购买状态丢失、产品信息加载失败、订阅优惠接入时的签名校验，以及老代码迁移到 StoreKit 2 时的边界情况。如果你正在做内购适配、会员开通或订阅恢复相关的维护工作，这篇应该能帮你少走不少弯路。

1. StoreKit 在 iOS 17.4 里到底动了什么

1.1 为什么一次系统升级会引发大量内购问题

先说背景。iOS 17.4 表面上看只是一次常规版本更新，但内购相关的底层逻辑其实做了不少调整。最明显的一点是苹果在这个版本里正式把 StoreKit 2 作为默认推荐路径，旧版 StoreKit 1 仍然兼容，但官方文档里明确标注为遗留状态。这意味着很多之前“能用就行”的写法开始暴露出问题，尤其是那些混用两套 API 的项目。

我遇到的第一批反馈来自用户：有人反馈“购买之后转圈圈，重进应用却显示已经扣款”，还有人反馈“订阅到期前被提前判定为失效”。一开始我以为是服务端回调没处理好，后来查了崩溃日志，发现大量错误指向 StoreKit 的事务处理模块。这才意识到问题出在客户端对交易流的消费方式上，而不是业务逻辑本身。

1.2 故障高发场景与对外表现清单

结合我在某应用上做的适配测试，以及同行的沟通情况，iOS 17.4 上常见的内购问题大概可以分成下面几类：

这些问题的共同特点是：不是每次都必现，而是依赖用户状态和时序。所以我建议遇到这类问题，不要只看是否崩溃，先检查事务处理链路是否合规。

2. 交易流程崩溃与重复发货的根因分析

2.1 崩溃日志里的 STFault 与事务完成顺序

iOS 17.4 中交易崩溃的典型堆栈会指向 Transaction.updates 的异步迭代器。很多老项目为了平滑迁移，StoreKit 1 的 SKPaymentQueue 代理没有删掉，同时又接入了 StoreKit 2 的 Transaction.updates 监听。两套监听并存时，同一笔交易会被两个通道同时接收，事务的状态流转就会出现竞争。

崩溃日志里经常看到一个以 STFault 开头的错误，附带信息是事务已经被标记完成或已失效。这个错误的含义很直接：代码在交易的终态之后还尝试去 finish 它。比如 StoreKit 1 的代理先走完了 paymentQueue(_:updatedTransactions:)，把交易标成已完成，StoreKit 2 的更新流又收到同一个事务，再去调用 finish()，这时候底层就会返回一个无效操作错误。

我的排查思路是先停掉旧代码的监听。确认业务逻辑不依赖 StoreKit 1 的 updatedTransactions 回调之后，把旧通道完全关闭，保留一套监听入口。这里要特别提醒，不要试图用“两边都监听、然后靠业务去重”的方案来兜底，重复发货的坑比想象的深。

2.2 未验证交易处理不当引发的权益重复发放

还有一个容易被忽略的细节：Transaction.updates 返回的枚举不是只有 .verified 这一个有效状态，还会出现 .unverified。很多代码在 .unverified 分支里直接打印了错误然后跳过，这在旧版本上可能还好，但 iOS 17.4 上如果碰到网络抖动或票据校验临时失败，未验证的交易被跳过之后并不会自动消失。等用户重新购买同款商品，服务端会看到两笔待处理交易，权益就可能发两次。

正确的做法是区分处理：.verified 走正常发货流程，.unverified 不要直接 finish，而是记录日志、上报到自己的监控平台，并把它保留在待处理队列里，等网络恢复或者下次启动时再尝试重新验证。我在这段时间里踩过这个坑，最严重的一次是用户积分数值翻倍，起因就是未验证交易被跳过，用户又重试了一次。

2.3 落地修复代码：事务流的正确消费方式

在我实际的项目里，事务监听的最终实现大致是这样：

swift复制private func startTransactionObserver() async {
    for await update in Transaction.updates {
        switch update {
        case .verified(let transaction):
            // 1. 先判断是否已经处理过，用本地记录或服务端凭证做幂等
            guard !isTransactionHandled(transaction.id) else {
                await transaction.finish()
                continue
            }
            // 2. 发起服务端验单，验单成功后才发放权益
            let result = await verifyOnServer(transaction)
            if result.isValid {
                await deliverPurchasedContent(transaction)
            }
            // 3. 权益发放完成后才允许 finish
            await transaction.finish()
        case .unverified(let transaction, let verificationError):
            // 不调用 finish，记录错误并加入重试队列
            pendingUnverifiedTransactions.insert(transaction.id)
            logVerificationFailure(transaction.id, error: verificationError)
        }
    }
}

这段代码里有三个关键点值得展开说说。

第一，幂等判断必须放在最前面。不光是本地文件记录，最好能让服务端也做一次去重，因为同一个事务 ID 客户端可能因为崩溃、杀进程、重启等原因重复触发多次。第二，服务端验单要在本地发货之前完成。很多团队为了省事，客户端看到 .verified 就直接发货，然后把凭证丢给服务端异步核对。这种顺序在正常网络情况下没问题，但一旦服务端验单失败，权益已经发出去了，要回滚非常困难。第三，finish() 的调用时机在 iOS 17.4 上比之前更敏感，所有分支都要走到，否则事务会一直留在更新流里，每次启动都会重新推一遍。

3. 恢复购买与状态丢失的排查与修复

3.1 AppStore.sync() 在 17.4 上的表现变化

恢复购买是内购应用里最容易被低估的功能。很多产品经理会把它理解为“帮我查到历史订单”，但技术上并不是这样。AppStore.sync() 的作用是同步当前账号在应用商店的购买权益，它不会把所有历史订单原样返回给你。在 iOS 17.4 上，这个方法的调用时长和失败率都有上升，尤其是在账号名下挂了很多订阅、退款记录的时候。

我实测遇到的情况是：调用 AppStore.sync() 之后，如果紧接着就去遍历 Transaction.currentEntitlements，很可能会拿到空列表。原因是同步操作虽然返回了成功，但权益数据还需要一点时间落地到本地事务库。苹果在 17.4 里调整了同步的时序，导致之前的“同步完立刻读取”写法集体失效。

3.2 currentEntitlements 与最新交易的取舍

Transaction.currentEntitlements 返回的是当前账号拥有的有效订阅和非消耗型购买，它不包括失效的订阅，也不包括退款成功的交易。所以拿它来判断“用户当前是否有权限”是合理的。但如果用它来判断“用户历史上买过什么”，就完全不对了。

在恢复购买的处理上，我建议把 AppStore.sync() 和 Transaction.currentEntitlements 配合起来，并且要给读取留出必要的等待时间，或者采用轮询的方式。不要同步完就立刻读一次，读不到就直接显示“没有购买记录”，那是把正常的时序问题硬生生变成了用户投诉。

3.3 推荐的恢复购买流程

下面是我调完 iOS 17.4 之后在用的恢复购买流程，简单来说就是“同步 + 等待 + 重复读取 + 服务端兜底”：

swift复制func restorePurchases() async throws -> [Transaction] {
    // 1. 发起同步
    try await AppStore.sync()

    // 2. 轮询等待权益数据稳定，最多重试 5 次
    var restored: [Transaction] = []
    for _ in 0..<5 {
        var transactions: [Transaction] = []
        for await entitlement in Transaction.currentEntitlements {
            if case .verified(let transaction) = entitlement {
                transactions.append(transaction)
            }
        }
        if !transactions.isEmpty {
            restored = transactions
            break
        }
        try await Task.sleep(nanoseconds: 500_000_000)
    }

    // 3. 如果客户端读不到，让服务端用最新凭证再查一次
    if restored.isEmpty {
        let serverTransactions = try await queryServerForActivePurchases()
        restored = serverTransactions
    }

    return restored
}

代码本身不复杂，重点是第 2 步的轮询。这个等待时间不是随便加的，而是因为 17.4 上本地事务库的更新是异步落盘的，同步接口返回时数据还没有完全就绪。轮询三次通常就可以看到权益出现，如果五次还读不到，基本可以判断该账号确实没有有效权益，再调服务端兜底也是一样。

提醒：恢复购买里一定要处理好“无购买记录”的提示文案。我从测试用户那边收到的反馈是，直接弹“您没有购买记录”会被理解成“以前买的都没了”，非常容易引发客诉。

4. 产品信息加载失败与价格展示异常

4.1 Product 请求失败的常见原因

除了交易链路，iOS 17.4 里 Product.products(for:) 这个接口也出现过加载失败的现象。具体表现是商品列表偶尔空白，杀掉 App 重进又好了，或者价格显示的是几天前的旧数值。排查后我发现，这类问题大多数不是 StoreKit 本身挂了，而是请求参数和缓存策略的问题。

有几种常见原因。一是商品 ID 和应用商店后台配置不一致，多了一个空格或者大小写错误，就会导致整批请求失败，而且错误日志里不一定直接告诉你哪个商品 ID 出问题。二是请求时机不对，比如在应用刚启动、网络还没就绪的时候就发起请求，又恰好命中了一次临时网络错误。三是 StoreKit 2 在 17.4 上对本地缓存的处理方式有调整，旧版本会静默读取缓存，新版本更倾向于让开发者主动处理缓存失效，这导致旧逻辑下依赖缓存展示的商品价格没有刷新。

4.2 缓存价格与订阅优惠的不一致性

价格展示问题如果仅仅发生在普通商品上，优先级还不高。但如果你接了订阅功能，尤其是加了续费优惠、推广优惠或者赢回优惠，那就必须重视了。iOS 17.4 新增了对赢回优惠（Win-back Offer）的支持，这类优惠专门用来吸引已经退订的用户重新订阅。接入之后，同一个商品在系统弹窗里展示的价格，可能会因为用户是否有资格使用优惠而不同。

我遇到的情况是，产品列表页展示的是正常月付价格，用户点进去之后系统弹窗里却显示了一个优惠价。这本身是正常现象，但如果客户端把产品信息缓存下来了，就会出现“列表页价格不变、弹窗价格变了”的奇怪组合，用户会怀疑价格显示错误。

处理思路是：不要对订阅产品的价格做长期缓存。每次进入订阅页面时重新拉取 Product，同时读取 product.subscription?.winBackOffers，把用户是否有资格使用优惠的逻辑放在服务端判断，而不是客户端猜测。因为客户端并没有可靠的方式判断用户是否满足赢回优惠的使用条件，这块逻辑必须依赖应用商店服务端的资格信号。

4.3 处理建议

在代码层面，我是这样处理的：

swift复制func loadProducts(ids: Set<String>) async throws -> [Product] {
    // 每次都走网络，不读本地缓存
    let products = try await Product.products(for: Array(ids))
    // 设置一个短路保护，避免空数组被上层当作“商品不存在”
    guard !products.isEmpty else {
        throw StoreKitError.invalidProductIDs
    }
    return products
}

不要再手动缓存产品价格。如果需要提升加载速度，应该把商品的基础信息（名称、描述、图标）放在自己服务端，价格和优惠一律实时取。这样虽然每次进入页面会多一点网络开销，但可以保证价格、优惠信息始终是最新的。对订阅场景来说，准确性远比加载速度重要。

另外要留意的是，Product.products(for:) 的请求结果里不包含用户具体的优惠资格，它只返回商品当前的价格点、促销优惠列表等静态信息。你必须让服务端通过应用商店服务端 API 查询用户的订阅状态以及可用的优惠报价，再下发到客户端展示。混用这两个数据源的时候，很容易出现“服务端说可以优惠、客户端却显示原价”的情况。关键原则是客户端展示价格前先和服务端对齐资格，不要凭本地缓存或本地判断。

5. 沙盒测试与上架前的检查清单

5.1 沙盒用户切换与登录态残留

iOS 17.4 的沙盒环境也有一些变化，最典型的坑是账户切换后 StoreKit 仍然缓存在上一个沙盒账号的登录态。很多时候你在设置里退出沙盒账号，重新登录另一个，但应用里调 AppStore.sync() 返回的还是老账号的交易记录。这个问题在 17.4 上尤其明显，因为它对本地事务库做了更强的缓存。

我的做法是，在应用的调试模式里加一个隐藏的“清空 StoreKit 本地状态”入口。具体代码不复杂，就是删除沙盒本地存下的交易记录文件，同时清掉 Transaction.updates 待处理队列里的残留事务。这个入口只在 DEBUG 编译条件下开放，不进入正式包。有了它，测试恢复购买和切换账号就快很多。

如果你不想加代码，也可以在测试前从设置里彻底退出所有账号，然后重启一次设备。这个土办法实测有效，但比较浪费时间，只适合偶尔手动验证。

5.2 测试中恢复购买失效的临时绕过方案

有段时间我在测试恢复购买时一直失败，排查到最后发现是沙盒环境里没有可恢复的历史交易。具体原因是：那笔订阅在创建时就不是通过当前集成方式购买的，或者已经过了退款期，就不在可恢复列表里了。

这就引出一个容易误导的问题：恢复购买测试不能随便拿一笔旧订单。正确做法是先创建一笔全新的沙盒订阅，任意订阅期限都行，确认购买成功后再推后台或者切换账号，最后点击恢复购买。测试前提是这笔订阅仍然处于有效期内。如果过期了，恢复结果为空是正常的，不代表代码有 bug。

另外，iOS 17.4 开始，沙盒环境对订阅的“快速过期”调试能力支持更好了。你可以在应用商店后台的开发者设置里开启沙盒自动续期加速，让 1 分钟模拟一天的订阅周期。这样测试恢复购买时可以更快看到过期后的状态变化。不想等真实周期的话，这一步几乎必须开启。

5.3 审核上架前的验收清单

最后整理一份我每次上架前都会过的验收清单，对照检查能少踩很多坑：

这份清单并不复杂，但每一项都能对应到前面说过的某类故障。我因为在旧监听通道没清理干净的情况下测试过一次，结果同一笔订阅在沙盒里被识别成了两笔，积分翻倍，后面排查花了大半天。如果当时有这份清单，至少能少踩一半的坑。

另外还想强调一下服务端的问题。iOS 17.4 之后，App Store Server API 返回的订阅状态信息会更严格地要求校验签名，而且交易的环境字段会明确区分沙盒和生产。如果你服务端验单时同时接入了沙盒和生产环境的回调，需要特别注意环境字段的切换。我见过最隐蔽的问题是：开发者在服务端把沙盒环境当成了正式环境，结果测试同学的订阅被判定为正式购买，权益、订单号全部混在一起，清理起来极其痛苦。

所以服务端这边有三个点必须确认：验单接口是否区分环境、同账户两个环境的事务是否隔离、通知回调里签名和交易的解析是否完整支持 JWS 格式。这三点在 17.4 上如果没做到，客户端再怎么调也白搭。

6. 常见问题速查表与独家避坑经验

6.1 问题、原因与解决方案对照

下面这个表是我按场景整理的速查清单，基本覆盖了 iOS 17.4 适配过程中团队里最常被问到的问题。

这张表可以作为适配完成后的回归测试清单，也可以直接发给测试同学，作为功能验证的参考。

6.2 我在实际适配过程中沉淀的几条经验

最后分享几个零散但实用的心得。

第一，线上问题不要只盯着 App 侧。这轮适配里，我花了很多精力在客户端排查，最后发现有几个问题的根因其实在服务端验单逻辑上：服务端没有处理 JWS 签名的中转，导致回调里的这个字段被丢弃，然后客户端无论怎么校验都会失败。所以排查优先级建议先确认服务端验单，再回头查客户端。

第二，Transaction.updates 的迭代器不能只在一个地方消费。如果你在多个模型里同时创建了多个 for await update in Transaction.updates，每个监听都会收到同一批事务，次数多了自然会出现重复处理和 finish 冲突。正确做法是把监听统一放到一个单例或者一个生命周期管理器里，由它把结果转发给业务层。

第三，17.4 对事务的校验比之前更严格，.verified 只是保证签名合法，不保证这笔交易在业务上一定有效。比如退款的交易，它的签名也是合法的，也能通过 .verified 返回，但你的业务逻辑里必须检查退款状态或者订阅失效状态。我就见过有团队只判断 .verified 就发权益，结果用户退款之后权益没有及时收回，造成客诉。

第四，不要相信本地存储的事务 ID。因为 StoreKit 的事务 ID 在客户端存储里可能会被重置，尤其是在用户重装应用、换机的情况下。判断一笔交易是否已经处理过，最可靠的方式是拿 transactionId 问服务端，而不是拿本地文件比对。本地记录只能作为启动时的缓存，最终判定要以服务端为准。

从这次 iOS 17.4 的适配经历来看，StoreKit 的问题大多数不是框架本身多么脆弱，而是迁移过程中留下的模糊地带太多。两套 API 并存、事务消费时机不严谨、服务端验单能力不足，这三个隐患叠加起来，才会在版本更新后集中爆发。如果你目前正在排查这类问题，先对照第 1 节的故障分类确定自己属于哪一类，再按住第 2 到第 4 节里的处理思路逐项整改，最后用第 5 节的清单回归一遍，基本就能把问题压到可控范围。

我个人在过完这一轮之后最大的体会是：内购代码里最重要的不是购买那一瞬间的调用，而是事务的边界处理。你给用户发权益之前，先问自己三个问题：有没有可能重复触发？有没有可能在网络异常时把未验证的交易丢掉？服务端能不能兜底？三个问题都过关，这类故障就能避开绝大多数。