Flutter iOS Universal Link可打开App但无法跳转对应页面

核心问题点 #

1. 配置文件拼写错误：你的apple-app-site-association里写的componenents是错误拼写，正确应为components，这个问题会导致苹果无法正确识别路径匹配规则。
2. URL未传递给Flutter路由系统：你的AppDelegate虽然成功获取到Universal Link的URL，但没有将这个URL传递给go_router进行解析，因此App仅会打开首页，不会触发对应路由的跳转。

分步修复 #

1. 修正apple-app-site-association配置 #

将错误的componenents改为components，正确配置内容如下：

{
    "applinks": {
        "details": [
            {
                "appIDs": [
                    "XXXXXXX.com.my.appBundle"
                ],
                "components": [
                    {
                        "/": "/*"
                    }
                ]
            }
        ]
    }
}

修改完成后，重新将该文件部署到你的域名根目录或.well-known目录，确保苹果能拉取到更新后的配置。

2. 修改AppDelegate.swift，传递URL到Flutter侧 #

更新continue userActivity方法，获取到URL后通过MethodChannel发送给Dart代码，同时新增冷启动时的URL处理逻辑：

import UIKit
import Flutter
import Firebase

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return super.application(application, continue: userActivity, restorationHandler: restorationHandler)
    }
    
    // 将URL传递给Flutter
    if let flutterVC = window?.rootViewController as? FlutterViewController {
      let channel = FlutterMethodChannel(name: "com.my.app/deeplink", binaryMessenger: flutterVC.binaryMessenger)
      channel.invokeMethod("handleDeepLink", arguments: url.absoluteString)
    }
    
    return super.application(application, continue: userActivity, restorationHandler: restorationHandler)
  }

  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    FirebaseApp.configure()
    GeneratedPluginRegistrant.register(with: self)
    
    // 处理冷启动时的Deep Link（App此前处于关闭状态）
    if let url = launchOptions?[.url] as? URL {
      if let flutterVC = window?.rootViewController as? FlutterViewController {
        let channel = FlutterMethodChannel(name: "com.my.app/deeplink", binaryMessenger: flutterVC.binaryMessenger)
        channel.invokeMethod("handleDeepLink", arguments: url.absoluteString)
      }
    }
    
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

3. Flutter侧配置go_router处理跳转 #

在Dart代码中监听MethodChannel传来的URL，让go_router导航到对应页面：

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:go_router/go_router.dart';

// 定义路由规则
final _router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomePage(),
    ),
    GoRoute(
      path: '/mypath',
      builder: (context, state) => const MyPathPage(),
    ),
    // 其他自定义路由...
  ],
);

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  
  // 监听原生传递的Deep Link
  const deeplinkChannel = MethodChannel('com.my.app/deeplink');
  deeplinkChannel.setMethodCallHandler((call) async {
    if (call.method == 'handleDeepLink') {
      final String link = call.arguments as String;
      // 解析URL路径，交给go_router执行跳转
      _router.go(Uri.parse(link).path);
    }
  });
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routerConfig: _router,
      title: 'Your App Name',
    );
  }
}

4. 验证步骤 #

1. 重新打包并安装App到测试设备
2. 点击www.example.com/mypath类链接，确认App能跳转到对应路由页面
3. 可使用苹果官方工具验证Universal Link配置是否生效

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