iOS Universal Link 配置

一.Universal Link 是什么

Universal Link 是一种 HTTPS 链接与 App 的双向绑定机制。当用户点击特定的 HTTPS 链接时：

如果设备已安装对应 App，系统直接打开 App 并传递路径参数；
如果设备未安装 App，链接正常打开网页（Fallback）；
用户无需任何弹窗确认（DeepLink有弹窗需要确认才能打开）；
由系统（而非网页或 JS）完成判断与分发。

二.配置总体思路

模块	作用
服务器端	提供 `.well-known/apple-app-site-association` 文件，声明 App ID 与可处理路径
iOS客户端	在 App 的 Entitlements 文件中声明 Associated Domains，并实现接收逻辑

三.服务端配置

1.文件路径

必须放在服务器根目录下：

arduino 复制代码

https://your-domain.com/.well-known/apple-app-site-association

注意：

没有扩展名（不是.json）
必须能通过https访问
Content-Type必须是application/json

2.文件内容

json 复制代码

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCDE12345.com.xxx.xxx",
        "paths": ["/callback", "/user/*"]
      }
    ]
  }
}

字段说明：

appId：Apple Team ID + App Bundle ID（中间以 . 连接，Team ID 可以在你的苹果账号下获取）
paths：允许触发 Universal Link 的 URL 路径 apps
apps：固定写成空数组（旧字段，为兼容保留）

3.验证aasa合法性

shell 复制代码

curl -I https://your-domain.com/.well-known/apple-app-site-association

返回如下则代表配置正常

bash 复制代码

HTTP/2 200
content-type: application/json

或者使用aasa-validator，一个专门用来aasa文件合法性的网站：

四.iOS客户端配置

1.开启 Associated Domains

在 Xcode 中：

选中项目 → Signing & Capabilities → + Capability
搜索 "Associated Domains" 并添加。

注意⚠️：确保你的Provisioning Profile 支持该功能

添加域名规则： applinks:your-domain.com

注意：这里的域名必须与 .well-known 文件所在的域完全一致（不支持通配符）。

2.处理回调

如果你使用的原生开发：

Swift 复制代码

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, continue userActivity: NSUserActivity, 
                     restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
           let url = userActivity.webpageURL {
            print("👉 Universal Link 跳转：\(url.absoluteString)")
            // 在这里根据 url.path 判断跳转逻辑
        }
        return true
    }
}

如果你使用的Flutter开发，使用AppLinks处理。

5.调试与验证

当首次安装或重新签名时，系统会自动访问： your-domain.com/.well-known... 你可以在服务器日志中观察是否有来自 Apple 的访问请求。

注意：

这个一般会有延迟几个小时到一天不等。
如果更新了apple-app-site-association和重新配置了Associated Domains，一般通过发新版本或者删除app重新下载才生效。