排查应用链接问题

本指南介绍了常见问题以及如何排查这些问题。您还可以使用 Play 管理中心“深层链接”页面或 Android Studio App Links Assistant 中的问题排查工具。如需了解详情，请参阅应用链接开发者工具。

  • 问题：您点击了本应打开应用的链接，但该链接却在网络浏览器中打开，或显示消除歧义对话框。
  • 解决方案：
    • 检查 assetlinks.json：确保该文件是有效的 JSON 文件，可通过 https://<your-domain>/.well-known/assetlinks.json 访问，并且通过 HTTPS 提供，没有重定向。使用在线验证工具。
    • 验证 SHA-256 指纹：仔细检查 assetlinks.json 中的 sha256_cert_fingerprints 是否与应用版本的签名密钥指纹完全一致（如果您使用 Play 应用签名，请使用 Play 管理中心中的指纹）。签名应为大写。
    • 验证 autoVerify：确保 AndroidManifest.xml 中的 <intent-filter> 包含 android:autoVerify="true。
    • 检查服务器端重定向：从 http 到 https 或从非 www 网域到 www 的重定向可能会导致验证失败。
    • 强制重新验证：运行测试应用链接指南中的 ADB 命令，以获取最新的验证结果。
    • 诊断链接解析（Android 17 及更高版本）：运行 adb shell am start --debug-link -a android.intent.action.VIEW -d "<URL>"，检查哪些候选应用、清单 intent 过滤器和动态应用链接规则与网址匹配。如需了解详情，请参阅使用 debug-link 标志诊断链接解析。

Android 15 及更高版本上的动态规则未更新

  • 问题：您已更新 assetlinks.json 文件中的规则，但应用未处理新链接。
  • 解决方案：
    • 强制重新验证：测试更改的最可靠方法是使用 adb shell pm verify-app-links --re-verify <your-package-name> 强制重新提取。
    • 检查是否存在拼写错误：仔细检查规则中的模式匹配器是否存在语法错误。
    • 检查清单过滤规则：查看应用清单中的 intent 过滤器规则，确保链接路径未被滤除。如果链接被过滤掉，请放宽应用清单中 intent 过滤器的限制。
    • 诊断匹配规则（Android 17 及更高版本）：运行 adb shell am start --debug-link -a android.intent.action.VIEW -d "<URL>"，检查评估了哪些规则，并确定是否有排除规则 (allow = 1) 阻止了应用打开。请参阅使用 debug-link 标志诊断链接解析。

修正常见的实现错误

如果您无法验证 Android 应用链接，请检查是否存在以下常见错误。本部分使用 example.com 作为占位域名；执行这些检查时，请将 example.com 替换为服务器的实际域名。

intent 过滤器设置不正确
检查您是否在 <intent-filter> 元素中添加了不归您的应用所有的网址。
服务器配置不正确

检查服务器的 JSON 配置，并确保 SHA 值正确无误。

此外，请检查 example.com.（带有尾随英文句点）是否提供与 example.com 相同的内容。

服务器端重定向

如果您设置了如下所示的重定向，系统将不会验证应用的任何 Android App Links：

  • http://example.com到 https://example.com
  • example.com到 www.example.com

此行为可保护应用的安全性。

服务器稳健性

检查您的客户端应用能否连接到您的服务器。

无法验证的链接

出于测试目的，您可能会故意添加无法验证的链接。请注意，在 Android 11 及更低版本中，这些链接会导致系统不验证应用的所有 Android App Links。

assetlinks.json 中的签名不正确

验证您的签名是否正确，以及是否与用于为应用签名的签名一致。常见错误包括：

  • 使用调试证书对应用进行签名，并且 assetlinks.json 中只有发布签名。
  • assetlinks.json 中有小写签名。签名应采用大写形式。
  • 如果您使用的是 Play 应用签名，请确保您使用的是 Google 为您的每个版本签名的签名。您可以按照有关声明网站关联的说明，验证这些详细信息，包括完整的 JSON 代码段。

获取 bug 报告

对于难以重现的复杂问题，请捕获 bug 报告并进行分析。这可以提供有关验证流程和任何系统级错误的宝贵数据洞见。