Android 12 App Links验证legacy_failure无法唤起App问题

legacy_failure 是 Android 12（API 31）收紧 App Links 校验规则后出现的典型错误，代表新版校验逻辑无法通过旧配置的验证，按以下优先级逐一排查即可解决：

1. 修复 assetlinks.json 部署与内容问题 #

• 严格保证文件格式合法：你贴出的JSON内容里包含// staging key fingerprint这类行注释，标准JSON不支持注释语法，Android 12的校验解析器遇到注释会直接判定文件无效，低版本Android的校验逻辑做了容错会忽略注释，这是Android 10正常、12失效的高频诱因。必须删除所有注释、多余尾逗号，输出无多余格式的标准JSON再部署。
  合法内容参考：

  [
    {
      "relation": ["delegate_permission/common.handle_all_urls"],
      "target": {
        "namespace": "android_app",
        "package_name": "com.example",
        "sha256_cert_fingerprints": [
          "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77",
          "11:22:33:44:55:66:77:88:99:00:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB"
        ]
      }
    }
  ]
  

• 禁止所有跳转规则：所有在Manifest中声明的域名，必须能通过https://<域名>/.well-known/assetlinks.json直接返回200状态码和文件内容，不要配置任何3xx跳转——包括HTTP转HTTPS、裸域跳www子域、路径重写全不行，Android 12的校验客户端不会跟随任何跳转，直接判定校验失败。你之前用检测工具时而提示www子域未配置，基本就是跳转规则或子域文件部署不到位导致的。
• 校验响应头与访问权限：文件返回的Content-Type必须是application/json，不能是text/plain或其他类型；不要给文件路径加WAF拦截、身份校验、Cookie验证规则，保证公网任意无状态请求都能直接拿到完整文件内容。
• 核对签名指纹：通过keytool -list -v -keystore 你的签名文件路径命令重新导出对应安装包的SHA256指纹，不要直接复用旧记录，注意指纹是冒号分隔的全大写格式，不要漏写字符；debug包、staging包、生产包的指纹要分别对应，不要混填。

2. 修复 AndroidManifest.xml 配置问题 #

• 多域名显式声明：不要用*.example.com通配符匹配根域名，Android 12的App Links校验逻辑中，通配符仅能匹配二级及以上子域，无法匹配example.com本身；也不要把多个host写在同一个data标签里，每个域名单独写一个data标签，正确配置参考：

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

• 检查网络安全配置：如果自定义了networkSecurityConfig，不要给App Links对应的域名配置自签名证书信任、用户证书信任规则，校验客户端默认仅信任系统内置CA，自定义证书规则会直接导致校验失败。
• 重置应用验证状态：部分机型通过adb安装应用时不会自动触发验证，执行以下命令重置状态后重验证：

  adb shell pm uninstall com.example
  # 重新安装应用后执行
  adb shell pm verify-app-links --re-verify com.example
  # 等待10秒左右查询状态
  adb shell pm get-app-links com.example
  

  配置正确的情况下，对应域名的状态会显示为verified，不再返回legacy_failure。

3. 特殊场景适配 #

• 排查包名冲突：如果设备上同时安装了多个同包名的应用（比如staging包和生产包用了同一个package_name），会导致校验签名冲突，先卸载所有同包名应用，仅保留测试版本再触发验证。
• 国产ROM适配：小米、华为等部分定制Android 12 ROM，即使App Links验证通过，也不会默认授予链接跳转权限，需要手动进入「应用信息-默认打开-支持的链接」，手动开启对应域名的跳转权限。
• 无GMS设备适配：国行无Google服务的机型会走厂商自有校验逻辑，如果厂商校验服务网络不通，也会返回legacy_failure，可以先在搭载原生GMS的Android 12设备上测试，确认配置本身无误后再做ROM适配。

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