4. 关联文件配置实战

Deep Link 能否从浏览器或系统跳进 App，最终取决于两个“信任声明文件”是否被平台正确读取：iOS 侧的 apple-app-site-association（简称 AASA）和 Android 侧的 assetlinks.json。它们不是普通的静态资源，而是操作系统在安装/更新 App 时主动拉取、校验并缓存的“域名—应用”绑定凭证。本节围绕字段含义、签名与托管要求、多环境策略和常见错误排查展开，目标是让你能独立完成一次可验证的配置。

一、两个文件的字段详解

AASA 是一个无扩展名的 JSON 文件，iOS 9 之后支持 applinks 顶层键。核心结构如下：

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          {
            "/": "/product/*",
            "comment": "商品详情页"
          },
          {
            "/": "/promo/*",
            "exclude": true,
            "comment": "促销页走 H5"
          }
        ]
      }
    ]
  }
}

其中 appIDs 由 Team ID（10 位）与 Bundle ID 拼接，必须与签名证书中的 Team ID 完全一致；components 用 / 描述路径匹配规则，exclude 为 true 表示该路径不交给 App。旧版本使用 paths 数组，新项目建议直接用 components，因为它支持查询串和片段匹配。注意：appIDs 大小写敏感，Bundle ID 写错一个字母就会导致整条规则失效。

Android 侧的 assetlinks.json 是一个数组，每个元素声明一个应用与一组指纹的绑定关系：

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [
        "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:"
        + "A0:22:3D:E3:CE:30"
      ]
    }
  }
]

relation 固定为 delegate_permission/common.handle_all_urls，表示允许该应用处理所有该域名下的 URL；package_name 是应用包名；sha256_cert_fingerprints 是签名证书的 SHA-256 指纹，必须与最终安装包使用的签名一致。调试包、发布包、Google Play 重签名后的指纹都不同，这是 Android 侧最常见的失败原因。

AASA 与 assetlinks.json 的托管、校验与多环境映射 托管位置与要求 iOS：https://域名/.well-known/ apple-app-site-association Android：https://域名/.well-known/ assetlinks.json ● 必须 HTTPS，无重定向 ● Content-Type: application/json 平台校验时机 iOS：安装/更新后首次启动 通过 CDN 拉取并缓存 Android：安装后由 Play 服务 校验并写入 Digital Asset Links ● 校验失败不会报错，仅静默失效 ● 缓存导致修改后需重装验证 多环境映射策略 dev.example.com → 调试包 stg.example.com → 预发包 www.example.com → 正式包 每环境独立文件与指纹 ● 禁止跨环境复用指纹 ● 路径规则按环境隔离 一次完整校验链路（以 Android 为例） 安装 APK 读取签名指纹 拉取 assetlinks HTTPS 无重定向 比对指纹 package_name 匹配 写入绑定 允许处理 URL 排查要点： 指纹不匹配 → 检查签名证书；404/重定向 → 检查 .well-known 路径与 CDN 规则；JSON 语法错误 → 用 jq 校验；缓存未刷新 → 卸载重装或等待平台缓存过期。

二、签名与托管要求

两个文件都必须通过 HTTPS 提供，且不能有任何重定向。iOS 要求 AASA 放在 https://<domain>/.well-known/apple-app-site-association，Content-Type 为 application/json，文件本身不需要签名，但必须保证内容与 App 的 Team ID 一致。Android 的 assetlinks.json 同样放在 /.well-known/ 下，且必须能被公网直接访问，不能依赖登录态或鉴权。

签名方面，iOS 的信任来自 App 签名中的 Team ID，因此 AASA 中的 appIDs 必须与打包证书一致；Android 的信任来自 sha256_cert_fingerprints，它对应的是 APK 的签名证书指纹。如果使用 Google Play 应用签名，实际安装包的指纹是 Google 重签名后的指纹，必须从 Play Console 的“应用签名”页面获取，而不是本地 keystore 的指纹。这一点在接入初期极易踩坑。

常见误区：把 AASA 放在网站根目录而不是 /.well-known/ 下；或者用 302 跳转到 CDN 地址。iOS 和 Android 都不会跟随重定向，会直接判定校验失败。

三、多环境配置策略

生产实践中通常有 dev、staging、production 三套环境。推荐按域名隔离：dev.example.com 对应调试包，stg.example.com 对应预发包，www.example.com 对应正式包。每个环境维护独立的 AASA 和 assetlinks.json，其中 appIDs 和 sha256_cert_fingerprints 分别对应各自环境的签名。这样做的原因是：调试包和正式包的签名不同，如果共用一份文件，必然有一端校验失败。

路径规则也应随环境调整。例如 dev 环境可以放宽为 /product/* 和 /promo/* 全部交给 App，方便测试；生产环境则通过 exclude 把促销页留给 H5，避免用户被强制跳转。配置管理上，建议把两个文件纳入版本控制，用模板变量注入域名和指纹，部署时由 CI 生成最终文件并上传到对应 CDN 路径。

四、常见配置错误排查

排查时先确认“文件能否被公网直接访问”。用 curl -I 检查状态码和 Content-Type：

curl -I https://www.example.com/.well-known/assetlinks.json
# 期望：HTTP/2 200，content-type: application/json
# 若出现 301/302，说明存在重定向，需修正 CDN 规则

其次校验 JSON 语法。AASA 和 assetlinks.json 都不允许注释、尾逗号。可以用 jq 快速验证：

curl -s https://www.example.com/.well-known/apple-app-site-association | jq .
# 若报 parse error，说明 JSON 结构有误

第三，核对指纹。Android 可用 keytool 或 apksigner 查看实际签名指纹，再与 assetlinks.json 中的值逐字节比对。注意指纹中的冒号分隔和大小写不影响匹配，但字符必须完全一致。iOS 则检查 appIDs 的 Team ID 是否与 Xcode 中 Signing & Capabilities 显示的一致。

第四，处理缓存。iOS 会在安装后首次启动时拉取 AASA，之后可能缓存数天；Android 的 Digital Asset Links 也有缓存。修改文件后，最可靠的验证方式是卸载重装 App，或使用 adb shell pm verify-app-links --re-verify <package> 触发重新校验。若仍不生效，检查设备是否开启了“打开支持的链接”开关。

建议在 CI 中加入一个校验步骤：部署后自动请求两个文件，用脚本断言状态码为 200、Content-Type 正确、JSON 可解析、指纹与预期一致。这样可以把配置错误拦截在上线之前，而不是等用户反馈跳转失败。

最后给出一份可直接对照的检查清单：文件路径是否为 /.well-known/；是否 HTTPS 且无重定向；Content-Type 是否为 application/json；JSON 是否合法；appIDs 的 Team ID 与 Bundle ID 是否正确；sha256_cert_fingerprints 是否与最终安装包一致；多环境是否使用独立域名与独立指纹；修改后是否通过重装或 re-verify 验证。逐项确认后，Deep Link 的关联文件配置基本可以稳定落地。

← 上一章 📖 返回目录 下一章 →