Flutter应用Universal Links在iOS失效，Android正常的技术问询

核心问题 #

Flutter应用在Android端点击Gmail内Courier生成的链接可正常触发DeepLink，但iOS端无法唤起应用，已完成apple-app-site-association、Info.plist、AppDelegate、Entitlements等配置，需定位并解决Universal Links失效问题。

逐一排查与修复 #

1. 关联域名与apple-app-site-association配置错误 #

• 关联域名不匹配：Runner.entitlements中com.apple.developer.associated-domains的applinks:domain需替换为Courier生成链接的实际域名718d95b0-XXXX-test.ct0.app，修改后如下：

  <string>applinks:718d95b0-XXXX-test.ct0.app</string>
  

• apple-app-site-association文件有效性：
  • 确保文件放置在域名根目录或.well-known目录下（如https://718d95b0-XXXX-test.ct0.app/apple-app-site-association），且HTTPS可直接访问、无重定向，Content-Type为application/json。
  • 确认appID是苹果开发者账号的10位Team ID + 应用Bundle ID（如ABCDE12345.com.yourcompany.yourapp），大小写完全匹配Xcode中的配置。
  • paths配置["*", "/"]已覆盖所有路径，无需调整。

2. AppDelegate未处理Universal Links回调 #

当前AppDelegate仅实现了自定义URL Scheme的open url方法，但Courier生成的HTTPS链接属于Universal Links，会触发continueUserActivity回调，需补充该方法：

override func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url = userActivity.webpageURL {
        // 将链接传递给Flutter侧处理
        if let controller = window?.rootViewController as? FlutterViewController {
            let channel = FlutterMethodChannel(name: "BundleId/deeplink", binaryMessenger: controller.binaryMessenger)
            channel.invokeMethod("onDeepLinkReceived", arguments: url.absoluteString)
        }
        return true
    }
    return super.application(application, continue: userActivity, restorationHandler: restorationHandler)
}

3. 邮件客户端的特殊行为 #

iOS端Gmail默认会在内部浏览器打开链接，若Universal Links配置正确，链接右上角会显示「打开应用」按钮，可引导用户点击。若需直接唤起应用，可检查Courier邮件模板是否支持设置链接的关联域相关参数，但优先确保系统层面的Universal Links配置生效。

4. 测试验证步骤 #

• 使用苹果官方的Associated Domains Debugger验证apple-app-site-association文件是否匹配你的App ID。
• 卸载重装应用（iOS仅在首次安装时下载关联文件，修改配置后需重装生效）。
• 使用真机测试（模拟器对Universal Links支持有限），先通过Safari直接打开链接，确认是否能唤起应用，排除邮件客户端的干扰。
• 确认Xcode中Build Settings的Associated Domains已开启，且与entitlements配置一致。

总结修复流程 #

1. 修正Runner.entitlements中的关联域名
2. 在AppDelegate中补充Universal Links的回调处理
3. 验证apple-app-site-association文件的正确性与可访问性
4. 卸载重装应用，用真机测试Safari唤起情况
5. 若Safari可正常唤起，说明问题出在邮件客户端的链接处理逻辑

内容的提问来源于stack exchange，提问作者Sarah Sami