iOS Universal Link 配置

一、先搞懂：Universal Link 是啥？

简单说，它就是一个普通的 https 网址（比如https://xxx.com/app），但配置后能直接跳转到你的 App 里，不用经过 Safari 浏览器。比如用户在微信里点这个链接，直接打开你的 App 对应页面，而不是跳浏览器，体验比传统的 URL Scheme 好太多（不用弹 “是否打开 App” 的提示）。

二、配置前的准备（必须先搞定）

1. 域名要求：要有一个已备案的域名，且支持HTTPS（必须用 SSL 证书，比如 Let’s Encrypt 免费证书也行）；
2. 开发者账号：苹果开发者账号（付费，99 美元 / 年），用来配置 App ID 和签名；
3. Xcode：最新版 Xcode，用来配置项目；
4. 文件服务器：能在域名根目录 / 指定路径放置配置文件（apple-app-site-association）。

三、分步配置（核心步骤，一步都不能少）

步骤 1：在苹果开发者后台配置 App ID

1. 登录苹果开发者中心，进入 “Certificates, Identifiers & Profiles”；
2. 找到你的 App ID（没有就新建），勾选 “Associated Domains”（关联域名），保存并重新生成 Provisioning Profile（配置文件）；
3. 下载新的配置文件，导入到 Xcode 中。

步骤 2：在 Xcode 中配置关联域名

1. 打开 Xcode 项目，选择 Targets → 你的 App → Signing & Capabilities；
2. 点击 “+ Capability”，添加 “Associated Domains”（关联域名）；
3. 在 Domains 栏添加：applinks:你的域名（比如applinks:xxx.com），注意不要加 https，直接写域名。

步骤 3：创建 apple-app-site-association 文件（关键）

这是苹果用来验证域名和 App 绑定关系的文件，无后缀、无扩展名（不是.txt，也不是.json）。

1. 文件格式（JSON）：

json

 

 

 

 

 

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TeamID.BundleID",  // 替换成你的团队ID+App Bundle ID
        "paths": [ "/app/*", "/" ]    // 匹配的路径，*是通配符，比如/app/*表示https://xxx.com/app/xxx都能跳转
      }
    ]
  }
}

 

• TeamID：苹果开发者后台 “Membership” 里能看到；
• BundleID：你的 App 的唯一标识（比如 com.xxx.xxx）；
• paths：指定哪些路径能触发跳转，["*"]表示所有路径都可以（测试用，正式环境建议精准匹配）。

2. 放置文件：
   • 方式 1（推荐）：放在域名的根目录（比如https://xxx.com/apple-app-site-association）；
   • 方式 2：放在.well-known目录下（https://xxx.com/.well-known/apple-app-site-association）；
   • 要求：文件必须能通过 HTTPS 访问，且MIME 类型为 application/json（服务器配置，比如 Nginx 添加：add_header Content-Type application/json;）。

步骤 4：App 内处理跳转逻辑

在 AppDelegate 或 SceneDelegate 中实现跳转回调，处理链接对应的页面：

swift

 

 

 

 

 

// iOS 13+ SceneDelegate
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
        let url = userActivity.webpageURL  // 获取跳转的Universal Link地址
        if let url = url {
            // 解析url，跳转到对应页面
            print("跳转链接：\(url)")
            // 示例：如果是https://xxx.com/app/detail，跳转到详情页
            if url.path.contains("/app/detail") {
                // 执行跳转逻辑
            }
        }
    }
}

// 兼容iOS 12及以下 AppDelegate
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
        let url = userActivity.webpageURL
        // 同上，解析url并跳转
    }
    return true
}

 

四、验证与测试

1. 验证 apple-app-site-association 文件

用苹果官方验证工具：https://app-site-association.cdn-apple.com/a/v1/你的域名比如https://app-site-association.cdn-apple.com/a/v1/xxx.com，能看到文件内容且无报错就没问题。

2. 真机测试（必须真机，模拟器不行）

1. 用 Xcode 将 App 安装到真机；
2. 在 Safari 中输入你的 Universal Link（比如https://xxx.com/app），长按链接会出现 “在 [你的 App 名] 中打开”；
3. 直接点击链接，能跳转到 App 并触发上面的回调方法，就是配置成功。

五、常见坑（新手必看）

1. 文件访问问题：apple-app-site-association 文件必须能被外网访问，且没有重定向；
2. 签名问题：Xcode 的签名必须包含 Associated Domains，否则配置不生效；
3. 路径匹配：paths 配置要精准，比如/app/*不能写成/App/*（大小写敏感）；
4. 缓存问题：苹果会缓存配置文件，测试时可重启手机或重置设置（设置→通用→传输或还原 iPhone→还原→还原所有设置）。

---

总结

1. Universal Link 配置核心是域名 HTTPS+apple-app-site-association 文件 + Xcode 关联域名 + 开发者后台开启权限；
2. 关键文件 apple-app-site-association 要无后缀、能通过 HTTPS 访问，且 AppID 和路径配置准确；
3. 测试必须用真机，遇到不跳转先检查文件访问和签名配置。