iOS Universal Links 配置后无法跳转？

Question

iOS Universal Links 配置后无法跳转的常见问题之一是：**apple-app-site-association（AASA）文件未正确部署或响应头配置不当**。该文件需通过 HTTPS 根域名或 .well-known 目录下可访问，且不能重定向或返回 404/500 错误。部分服务器默认不识别 `.json` 或 AASA 文件类型，导致 MIME 类型缺失，也会影响下载。此外，AASA 文件格式错误、缺少必要字段（如 apps、components）、团队 ID 不匹配或 Bundle ID 未在其中声明，均会导致系统校验失败，使 Universal Links 降级为普通网页链接。开发时需使用 Apple 的验证工具或设备日志确认 AASA 是否被正确获取与解析。

Answer 1

1. iOS Universal Links 基础概念与 AASA 文件作用

iOS Universal Links 允许用户点击一个 HTTPS 链接后直接跳转至已安装的应用，提升用户体验。实现该功能的核心是 apple-app-site-association (AASA) 文件。该文件由 Apple 定义，用于声明哪些 URL 路径可被特定 App 关联。当用户点击链接时，iOS 系统会从应用关联域名下载 AASA 文件并校验其内容，确认是否应启动本地 App。

AASA 文件必须部署在支持 HTTPS 的服务器上，并可通过以下任一路径访问：

• https://yourdomain.com/.well-known/apple-app-site-association
• https://yourdomain.com/apple-app-site-association

注意：iOS 优先查找 .well-known 目录下的版本，若不存在则尝试根目录。此外，该请求过程中不允许发生任何重定向（如 301/302），否则会导致文件获取失败。

2. AASA 文件部署的常见技术问题分析

尽管配置流程看似简单，但在实际部署中常出现多种导致 Universal Links 失效的问题。以下是按严重程度排序的典型场景：

1. 服务器未启用 HTTPS 或证书不被信任
2. AASA 文件路径错误或返回 404/500 状态码
3. 响应包含重定向（HTTP 3xx）
4. 服务器未正确设置 MIME 类型（应为 application/json 或无类型也可接受）
5. 文件扩展名处理不当（部分服务器需显式支持无扩展名或 .json）
6. AASA 内容格式非法（非有效 JSON）
7. 缺失关键字段：applinks, apps, components
8. Team ID 与开发者账户不匹配
9. Bundle ID 未在 AASA 中声明
10. App Store Connect 中未启用 Associated Domains 功能

3. 服务器配置检查清单与解决方案

检查项	推荐配置	验证方法
协议安全性	必须使用 HTTPS，且证书链完整可信	curl -I https://domain/.well-known/apple-app-site-association
HTTP 状态码	200 OK，禁止 3xx/4xx/5xx	浏览器开发者工具 Network 面板
MIME 类型	application/json 或空均可	查看响应头 Content-Type
文件可访问性	无需身份认证，公开可读	匿名访问测试
缓存策略	建议设置 Cache-Control: max-age=86400	避免频繁重复下载

4. AASA 文件结构示例与字段详解

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCDE12345.com.example.app",
        "paths": ["/articles/*", "/profile", "NOT /admin/*"]
      }
    ]
  }
}

其中：

• apps 字段必须为空数组（历史遗留字段，现由 App ID 推导）
• appID = TeamID + BundleID，必须与签名一致
• paths 支持通配符和排除规则（NOT）
• 整个文件不能有注释、尾随逗号等非法 JSON 结构

5. 调试流程图与日志分析方法

graph TD A[用户点击HTTPS链接] --> B{iOS是否已缓存AASA?} B -- 是 --> C[解析components规则] B -- 否 --> D[发起HTTPS请求获取AASA] D --> E{响应成功且格式正确?} E -- 否 --> F[降级为Safari打开] E -- 是 --> G[校验Team ID与Bundle ID] G --> H{匹配成功?} H -- 是 --> I[启动App并传递URL] H -- 否 --> F

调试时可通过如下方式捕获系统行为：

• 使用 macOS 控制台连接设备，过滤 swcd 进程日志（负责 AASA 下载）
• 执行 log show --predicate 'subsystem contains "com.apple.swc"' --last 1h
• 观察是否有 Failed to load AASA 或 Domain not allowed 错误