Flutter Android冷启动状态下AppLinks深度链接失效求助

问题分析 #

Android冷启动（彻底清除后台后启动）时深度链接失效，核心原因是应用启动时的初始Intent未被AppLinks正确捕获，或是AndroidManifest配置存在遗漏，导致系统无法将深度链接的Intent传递给Flutter端的getInitialAppLink()方法。

解决方案 #

1. 修正AndroidManifest.xml配置 #

确保MainActivity的启动模式和Intent过滤器配置正确，这是Android端深度链接生效的基础：

<activity
    android:name=".MainActivity"
    android:launchMode="singleTask" <!-- 关键：复用任务栈，保证Intent能传递到正确实例 -->
    android:exported="true">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- 替换为你的深度链接域名和scheme -->
        <data
            android:scheme="https"
            android:host="your-domain.com" />
    </intent-filter>
</activity>

• singleTask模式：避免冷启动时创建多个Activity实例，确保深度链接Intent能被当前实例接收。
• autoVerify="true"：配合assetlinks.json实现App Links自动验证，跳过应用选择器直接打开你的App。

2. 调整Flutter端初始化时机 #

确保深度链接初始化在Flutter绑定完成后执行，避免异步时机问题导致getInitialAppLink()返回null：

void main() async {
  // 提前初始化Flutter绑定，保证异步调用正常执行
  WidgetsFlutterBinding.ensureInitialized();
  
  // 初始化深度链接逻辑
  await initDeepLinks();
  
  runApp(const MyApp());
}

如果initDeepLinks()是在页面的initState中调用，同样需要先确保绑定初始化：

@override
void initState() {
  super.initState();
  WidgetsFlutterBinding.ensureInitialized();
  initDeepLinks();
}

3. 添加初始链接捕获兜底逻辑 #

部分场景下getInitialAppLink()可能因系统Intent传递延迟返回null，可直接读取Android原生Intent作为兜底：

Future<void> initDeepLinks() async {
  _appLinks = AppLinks();
  
  Uri? appLink = await _appLinks.getInitialAppLink();
  
  // Android端兜底：直接读取原生Intent的data
  if (appLink == null && Platform.isAndroid) {
    final initialIntent = await AppLinks().getInitialIntent();
    appLink = initialIntent?.data;
  }
  
  if (appLink != null) {
    print('getInitialAppLink: $appLink');
    refresh();
    openAppLink(appLink);
  }
  
  _linkSubscription = _appLinks.uriLinkStream.listen((uri) {
    print('onAppLink: $uri');
    update();
    openAppLink(uri);
  });
}

4. 验证assetlinks.json配置（HTTPS链接场景） #

如果使用HTTPS协议的深度链接，需在域名根目录放置assetlinks.json，让Android系统验证应用与域名的关联：

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.app.package",
    "sha256_cert_fingerprints": ["你的应用签名SHA256指纹"]
  }
}]

可通过Android Studio的「App Links Assistant」工具自动生成并验证该文件。

测试建议 #

• 测试前彻底清除应用后台（从最近应用列表划掉）
• 使用adb命令模拟冷启动深度链接：

adb shell am start -W -a android.intent.action.VIEW -d "https://your-domain.com/activeOrder" com.your.app.package

观察控制台输出的getInitialAppLink日志，确认链接是否被正确捕获。

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