Flutter App Links/Universal Links配置异常求助：跳转逻辑不符预期

Android Chrome 无法跳转的问题 #

• 确认Manifest配置：Android 12+必须给处理App Links的<intent-filter>加上android:autoVerify="true"，同时要包含VIEW动作、http/https scheme及你的域名。示例：

<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" />
    <data android:scheme="https" android:host="example.com" android:pathPrefix="/shared/" />
</intent-filter>

• 验证assetlinks.json：文件必须是合法JSON，包名、SHA256指纹要和签名文件完全一致（debug和release版本指纹不同，测试时要对应）。格式示例：

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.your.app",
      "sha256_cert_fingerprints": ["AA:BB:CC:..."]
    }
  }
]

注意指纹不能有空格，大小写要匹配。

• Chrome特殊处理：Chrome默认可能用内嵌页打开链接，要确保是直接点击的独立链接；首次打开时Chrome会弹出是否打开应用的提示，必须选“允许”才能正常跳转。

iOS 全场景无法跳转的问题 #

• 修正文件路径：你提供的apple-app-site-association路径多了一个斜杠，正确路径是https://example.com/.well-known/apple-app-site-association，路径错误会导致iOS无法读取配置文件。
• 检查文件内容：必须是无后缀的JSON文件，applinks字段里的details要包含Team ID+Bundle ID，以及匹配跳转URL的paths规则。示例：

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.your.app",
        "paths": [ "/shared/*", "/shared/?*" ]
      }
    ]
  }
}

paths要覆盖带参数的情况，比如/shared/?*能匹配你的测试链接。

• Xcode配置：在Signing & Capabilities里添加Associated Domains，条目填applinks:example.com，确保Team ID和Bundle ID和文件里的一致。
• 系统回调处理：iOS 14+要在SceneDelegate里处理Universal Links的回调，让uni_links能拿到链接。示例：

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url = userActivity.webpageURL {
    _ = try? UniLinksPlugin.shared.handleUniversalLink(url)
  }
}

• 清除缓存：iOS会缓存配置文件，测试时可以重启设备，或者用模拟器命令xcrun simctl openurl booted https://example.com/shared/?askdjfhj=aakjsndfkaj测试，避免缓存干扰。

未安装应用时跳转应用商店的处理 #

• 服务器端添加跳转逻辑：在https://example.com/shared/页面加一段JS，尝试唤起应用，若超时未唤起则跳转到对应应用商店。示例代码：

let isAppOpened = false;
// 尝试唤起应用
window.location.href = "yourapp://shared/?askdjfhj=aakjsndfkaj";
// 5秒后未唤起则跳转应用商店
setTimeout(() => {
  if (!isAppOpened) {
    const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
    window.location.href = isIOS 
      ? "https://apps.apple.com/us/app/你的应用/idAPP_ID" 
      : "https://play.google.com/store/apps/details?id=com.your.app";
  }
}, 5000);
// 监听页面隐藏（说明应用被唤起）
document.addEventListener("visibilitychange", () => {
  if (document.hidden) isAppOpened = true;
});

• Android端如果App Links验证通过，未安装时Chrome会自动提示去Play商店，但服务器端跳转更稳定，能覆盖更多场景。

uni_links 配置检查 #

• Flutter端正确监听链接：

import 'package:uni_links/uni_links.dart';

void initLinkListener() async {
  // 处理启动时的初始链接
  final initialLink = await getInitialLink();
  if (initialLink != null) _handleLink(initialLink);
  // 监听后续跳转链接
  linkStream.listen((link) {
    if (link != null) _handleLink(link);
  });
}

void _handleLink(String link) {
  final uri = Uri.parse(link);
  final param = uri.queryParameters['askdjfhj'];
  // 导航到详情页的逻辑
}

确保在应用启动时就调用initLinkListener()。

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