Flutter中app_links包Android端跳转失效问题求助

1. 验证 assetlinks.json 配置正确性 #

• 确保文件放在 https://你的域名/.well-known/assetlinks.json 路径下，注意是**/.well-known/** 专属目录，不能放错位置
• 核对文件内的 package_name 完全匹配 Android 项目的 applicationId（在 build.gradle 中定义），sha256_cert_fingerprints 要对应测试包的签名指纹（debug 和 release 环境指纹不同，别搞混）
• 直接用 Android Studio 的App Links Assistant（路径：Tools > App Links Assistant）里的「Validate Digital Asset Links File」功能一键验证，快速定位格式或内容错误

2. 检查 AndroidManifest.xml 配置细节 #

• 确认 <intent-filter> 嵌套在主 Activity（通常是 MainActivity）节点下，且必须包含 android:autoVerify="true" 属性——这是 Android 自动验证 assetlinks 的核心开关，示例配置：

  <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="你的域名" />
  </intent-filter>
  

• 避免定义多个冲突的 <intent-filter>，比如同时存在 http/https 双 scheme、多 host 规则，可能导致系统优先级判断混乱

3. 确保测试包签名与 assetlinks 匹配 #

• 用 debug 包测试时，必须使用 debug 证书的 SHA256 指纹，可通过命令获取：

  keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
  

• 如果使用自定义签名的 debug 包，要对应替换成该签名文件的指纹

4. 强制清除系统验证缓存 #

• Android 会缓存 assetlinks 的验证结果，修改后可能不会立即生效，可通过以下方式刷新：
  • 卸载应用后重新安装
  • 进入系统设置的应用详情页，找到「默认打开方式」清除链接关联记录
  • 用 adb 命令强制重新验证：

    adb shell pm verify-app-links --re-verify 你的应用ID
    

    执行后用下方命令查看验证状态，正常应显示 verified: true：

    adb shell pm get-app-links 你的应用ID
    

5. 核对 app_links 初始化逻辑 #

• 确保 Flutter 代码中正确初始化并监听链接，示例：

  void main() async {
    WidgetsFlutterBinding.ensureInitialized();
    final AppLinks appLinks = AppLinks();
    // 监听前台触发的链接
    appLinks.uriLinkStream.listen((Uri uri) {
      // 处理跳转逻辑
    });
    // 检查应用启动时的初始链接
    final Uri? initialUri = await appLinks.getInitialAppLink();
    if (initialUri != null) {
      // 处理启动链接
    }
    runApp(MyApp());
  }
  

• 不要遗漏 WidgetsFlutterBinding.ensureInitialized()，否则可能导致初始化失败

6. 排查浏览器兼容性 #

• 部分第三方浏览器可能不严格遵循 App Links 标准，先改用系统自带 Chrome 测试，确认是否是浏览器的问题
• 如果是第三方浏览器的问题，可添加 android:scheme="http" 的 filter 作为降级方案，但这会让链接变成「选择打开方式」，无法直接跳转应用

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