iOS端Universal Link可打开Flutter应用但无法跳转至指定页面

1. 检查iOS原生端是否正确传递跳转URL给Flutter #

iOS的Universal Links需要在原生代码中处理URL并传递给Flutter引擎，否则Flutter无法获取跳转路径，只能打开主页：

• 若使用AppDelegate模式，确保AppDelegate.swift包含以下代码：

  import UIKit
  import Flutter
  
  @UIApplicationMain
  @objc class AppDelegate: FlutterAppDelegate {
    override func application(
      _ application: UIApplication,
      open url: URL,
      options: [UIApplication.OpenURLOptionsKey : Any] = [:]
    ) -> Bool {
      return super.application(application, open: url, options: options)
    }
  }
  

• 若使用SceneDelegate模式，在SceneDelegate.swift中添加URL处理逻辑：

  func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
      guard let url = URLContexts.first?.url else { return }
      if let flutterViewController = window?.rootViewController as? FlutterViewController {
          flutterViewController.handle(url: url)
      }
  }
  

2. 验证Flutter是否接收到跳转URL #

在Flutter的main函数中打印默认路由名称，确认是否获取到跳转路径：

void main() {
  print('默认路由名称: ${WidgetsBinding.instance.platformDispatcher.defaultRouteName}');
  runApp(MyApp());
}

• 若打印结果始终为/，说明原生端未正确传递URL，回到第一步排查原生代码。

3. 检查go_router配置是否支持Deep Link #

确保go_router的路由表包含目标页面，且正确处理Deep Link：

• 确认路由表中存在/page1对应的路由配置；
• 可添加deepLinkBuilder显式处理跳转链接，验证是否接收到Deep Link：

  GoRouter(
    routes: [
      GoRoute(path: '/', builder: (context, state) => HomePage()),
      GoRoute(path: '/page1', builder: (context, state) => Page1()),
    ],
    deepLinkBuilder: (deepLink) {
      print('接收到Deep Link: ${deepLink.path}');
      return DeepLink.path(deepLink.path);
    },
    redirect: (context, state) { ... }
  )
  

• 若deepLinkBuilder未触发，说明Flutter未收到跳转URL，重点排查原生端。

4. 修正AASA文件的appID格式 #

AASA中的appID必须是TeamID.BundleID的组合，而非仅BundleID：

• 示例：若TeamID为ABC123XYZ，BundleID为com.my-app，则正确的appID应为ABC123XYZ.com.my-app；
• TeamID可在Apple Developer后台或Xcode项目的Signing & Capabilities页面查看。

5. 清除iOS模拟器的AASA缓存 #

iOS会缓存AASA文件，可能导致配置更新不生效：

• 卸载应用，重启模拟器后重新安装；
• 或在模拟器中进入设置 > Safari > 清除历史记录与网站数据；
• 极端情况可执行命令重置模拟器：xcrun simctl erase booted（会清除模拟器所有数据）。

6. 检查Xcode的Associated Domains配置 #

• 打开Xcode项目的Signing & Capabilities页面，确认Associated Domains中已添加正确的域名（如applinks:my-app.com）；
• 若跳转URL包含www前缀，需添加applinks:www.my-app.com到域名列表。

7. 查看iOS系统控制台日志 #

打开Xcode的Window > Devices and Simulators，选中目标模拟器后点击Open Console，执行跳转命令后搜索applinks或Universal Link，查看是否有错误提示定位问题。

8. 验证AASA文件的服务器配置 #

• 在模拟器的Safari中访问https://my-app.com/.well-known/apple-app-site-association，确认能正确下载文件且内容与配置一致；
• 确保服务器返回的MIME类型为application/json，而非text/plain（可通过浏览器开发者工具查看响应头）。

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