iOS 更新最新 SDK 后无法拉起支付宝 App 支付

2026-10-24支付小周

结论

更新支付宝 iOS SDK 后只能进入 H5 支付，通常并不是 payOrder API 失效，而是应用尚未完成新版 SDK 所需的跳转配置。SDK 无法确认或打开支付宝客户端时，就会降级到 H5 收银台。

先检查这三项：

Info.plist 是否配置了支付宝客户端的查询白名单；
调用 payOrder:fromScheme:callback: 时传入的 fromScheme 是否已经注册；
服务端生成的是否仍是 App 支付订单，而不是手机网站支付订单。

1. 配置支付宝 URL Scheme 查询白名单

iOS 限制了 canOpenURL: 查询。支付宝 SDK 需要通过它判断客户端是否已安装。如果相关 Scheme 没有加入 LSApplicationQueriesSchemes，查询可能失败，SDK 随后会转入 H5 支付。

在 Info.plist 中添加当前版本支付宝 SDK 要求的 Scheme，例如：

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>alipay</string>
    <string>alipayshare</string>
</array>

不同版本的支付宝 SDK 可能要求不同的白名单项，应以当前版本随附的官方接入文档为准，不要只沿用旧项目的配置。

使用 Xcode 图形界面时，可以在 Info 页面添加：

Queried URL Schemes
    Item 0: alipay
    Item 1: alipayshare

修改后，建议先删除设备上的旧 App，再重新安装，以免旧安装包的配置干扰排查。

2. 注册并正确传入回调 Scheme

fromScheme 是支付完成后，支付宝返回商户 App 的入口。它必须与项目中注册的 URL Scheme 完全一致，大小写也不能有差异。

在 Info.plist 中配置商户 App 自己的 Scheme：

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>alipay-callback</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourAppAlipay</string>
        </array>
    </dict>
</array>

调用支付接口时传入相同的值：

NSString *appScheme = @"yourAppAlipay";

[[AlipaySDK defaultService] payOrder:orderString
                         fromScheme:appScheme
                           callback:^(NSDictionary *resultDic) {
    NSLog(@"Alipay result: %@", resultDic);
}];

Swift 示例：

let appScheme = "yourAppAlipay"

AlipaySDK.defaultService().payOrder(
    orderString,
    fromScheme: appScheme
) { result in
    print("Alipay result: \(String(describing: result))")
}

不要把支付宝客户端的 alipay Scheme 传给 fromScheme。alipay 用于查询或拉起支付宝，fromScheme 则是商户 App 自己注册的回调标识。

3. 检查订单是否为 App 支付订单

如果客户端配置没有问题，但每次仍直接打开网页，就要检查服务端生成的订单参数。

支付宝 App 支付通常要求服务端按照 App 支付产品生成并签名订单。例如，在支付宝开放平台的常见接口中，业务参数应对应 App 支付产品：

{
  "subject": "订单标题",
  "out_trade_no": "202609090001",
  "total_amount": "0.01",
  "product_code": "QUICK_MSECURITY_PAY"
}

客户端应将服务端返回的完整签名订单字符串原样交给 SDK：

[[AlipaySDK defaultService] payOrder:orderString
                         fromScheme:@"yourAppAlipay"
                           callback:^(NSDictionary *resultDic) {
    // 这里只能作为同步结果提示。
    // 最终支付状态应由服务端查询或异步通知确认。
}];

如果服务端返回的是手机网站支付链接，或者客户端直接把网页 URL 交给 WebView、Safari，支付自然只会进入 H5 收银台。客户端不要重新拼接、编码或签名订单字符串。

4. 处理支付回跳

项目使用传统 App 生命周期时，可以在 AppDelegate 中处理回调：

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {

    if ([url.host isEqualToString:@"safepay"]) {
        [[AlipaySDK defaultService] processOrderWithPaymentResult:url
                                                 standbyCallback:^(NSDictionary *resultDic) {
            NSLog(@"Alipay callback: %@", resultDic);
        }];
    }

    return YES;
}

如果项目使用 Scene 生命周期，还需要在 SceneDelegate 中接收 URL：

- (void)scene:(UIScene *)scene
openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {

    NSURL *url = URLContexts.allObjects.firstObject.URL;
    if (url == nil) {
        return;
    }

    if ([url.host isEqualToString:@"safepay"]) {
        [[AlipaySDK defaultService] processOrderWithPaymentResult:url
                                                 standbyCallback:^(NSDictionary *resultDic) {
            NSLog(@"Alipay callback: %@", resultDic);
        }];
    }
}

回调处理错误通常会影响支付完成后的返回流程，不一定会直接导致支付宝 App 无法拉起。不过，升级 SDK 时仍应一并核对这部分配置。

排查顺序

可以按以下顺序检查：

确认测试设备已安装并能正常使用支付宝 App；
检查实际打包后的 Info.plist，确认其中包含 LSApplicationQueriesSchemes；
确认自定义回调 Scheme 已注册，并且与 fromScheme 完全一致；
确认调用的是支付宝 SDK 的 payOrder:fromScheme:callback:；
确认服务端生成的是 App 支付订单；
确认客户端没有主动将支付链接交给 WebView 或 Safari；
清理构建产物，卸载旧 App，然后重新安装测试；
查看 SDK 回调结果和控制台日志，区分“客户端不可用”“订单错误”和“签名失败”。

进入 H5 支付不等于 SDK 存在缺陷。多数情况下，这是客户端未满足跳转条件后触发的降级行为。如果以上配置都正确，还需要核对当前 SDK 的官方接入说明、集成方式及服务端支付产品配置。不同版本要求的白名单项和回调接入方式可能有所调整。