1. 从一次分享链接失效说起Universal Link 的共用困境去年帮一个做内容社区的朋友排查过一个挺典型的问题他们的 App 里有个邀请好友功能运营在后台生成一条分享链接用户点开后如果装了 App 就直接唤起没装就跳 App Store。一开始只有主 App 用这条链接跑得挺顺。后来他们又上线了一个极速版 App想让两个客户端共用同一条分享链接——结果就出事了极速版用户点链接十次有七八次被主 App 抢走偶尔两个都不唤起直接落在浏览器里。这个问题的核心就是多个客户端共用同一条 Universal Link时苹果的匹配机制到底怎么判定该唤起谁。很多人以为只要两个 App 的 Associated Domains 里都写上同一个域名就完事了实际上远没这么简单。苹果在 iOS 9 引入 Universal Link 之后又在后续版本里不断调整匹配优先级尤其是 iOS 13 之后引入了components和exclude这些精细匹配字段玩法完全变了。这篇内容我打算把这件事彻底讲透从 Universal Link 的底层匹配逻辑到两个甚至多个 App 共用一条链接时的配置方案再到实测中那些文档里不会写的坑。适合正在做多端 App 矩阵、马甲包、主端极速版这类架构的开发和运维同学。如果你只有一个 App看完也能把 Universal Link 的匹配规则吃得更透少踩几个坑。2. Universal Link 的匹配机制苹果到底怎么决定唤起哪个 App2.1 从 apple-app-site-association 文件说起Universal Link 的信任基础是域名根目录下的apple-app-site-association文件下面简称 AASA 文件。这个文件放在https://你的域名/.well-known/apple-app-site-association不需要签名但必须是application/json类型且不能有重定向。iOS 在安装 App 时会去拉取这个文件把里面声明的路径和当前 App 的 Team ID Bundle ID 建立关联。一个最基础的 AASA 长这样{ applinks: { apps: [], details: [ { appID: ABCDE12345.com.example.main, paths: [/share/*, /invite/*] } ] } }这里的appID是TeamID.BundleID的组合。关键点在于details是一个数组可以放多个 App 的条目。这就是多客户端共用的物理基础——同一个域名、同一个 AASA 文件里声明多个 App 的 appID理论上它们都能响应这个域名下的链接。但都能响应不等于都能被正确唤起。苹果的匹配是按顺序、按优先级来的谁先匹配上谁赢后面的就没机会了。这个顺序不是你在 AASA 里写的顺序而是苹果内部的一套规则。2.2 匹配优先级为什么主 App 总是抢走链接苹果的匹配逻辑大致是这样的当用户点击一个 Universal Link系统会遍历所有已安装的、在 AASA 里声明了该域名的 App然后按以下维度排序路径匹配的精确度components里写的条件越具体优先级越高。比如/share/invite/*比/share/*更具体。exclude字段的排除如果某个 App 的配置里明确exclude了某条路径那它就不会响应这条路径。App 的安装顺序和系统缓存这一条最玄学苹果没有公开文档但实测下来先安装的 App 在同等条件下有微弱优势。问题就出在第一条。如果两个 App 的 AASA 配置完全一样都写/share/*那系统就懵了——它没有明确的优先级依据只能按内部缓存顺序来表现就是随机唤起或者干脆都不唤起落到 Safari。这就是我朋友遇到的情况。注意很多人以为在 AASA 里把某个 App 的条目写在前面就能提高优先级这是错的。苹果不看数组顺序只看匹配条件的精确度。2.3 iOS 13 之后的 components 字段精细匹配的钥匙iOS 13 开始苹果推荐用components替代老的paths。components允许你对 URL 的各个部分做精确匹配和排除语法是这样的{ applinks: { details: [ { appID: ABCDE12345.com.example.main, components: [ { /: /share/*, ?: { channel: main }, exclude: false, comment: 主 App 只响应带 channelmain 的分享链接 } ] }, { appID: ABCDE12345.com.example.lite, components: [ { /: /share/*, ?: { channel: lite }, exclude: false, comment: 极速版只响应带 channellite 的分享链接 } ] } ] } }这个配置的思路是用 query 参数区分不同客户端。运营生成分享链接时根据目标客户端拼上不同的channel参数这样两个 App 的匹配条件就互斥了不会互相抢。但这里有个大坑components里的 query 匹配是精确匹配?channelmain只能匹配?channelmain如果链接里还有别的参数比如?channelmainfromwx那这条规则就匹配不上了。正确写法是用通配?: { channel: main* }或者干脆不写 query 条件改用路径区分。这个细节后面会展开讲。3. 多客户端共用的三种配置方案与选型逻辑3.1 方案一路径前缀区分最稳推荐这是我最推荐的方案逻辑最简单不同客户端用不同的路径前缀。主 App/main/share/*、/main/invite/*极速版/lite/share/*、/lite/invite/*AASA 配置{ applinks: { details: [ { appID: ABCDE12345.com.example.main, components: [{ /: /main/*, exclude: false }] }, { appID: ABCDE12345.com.example.lite, components: [{ /: /lite/*, exclude: false }] } ] } }服务端生成分享链接时根据业务决定用哪个前缀。这个方案的好处是匹配条件完全互斥不存在抢链接的可能而且路径语义清晰排查问题一眼就能看出该唤起谁。代价是运营侧要改链接生成逻辑如果历史链接已经发出去了得做 301 重定向兼容。我的做法是在服务端加一层路由老链接/share/*根据 User-Agent 或者默认规则重定向到/main/share/*保证老链接不失效。3.2 方案二Query 参数区分灵活但坑多如果不想改路径结构可以用 query 参数区分。前面提过components的 query 匹配是精确匹配必须用通配符。{ applinks: { details: [ { appID: ABCDE12345.com.example.main, components: [ { /: /share/*, ?: { client: main* }, exclude: false } ] }, { appID: ABCDE12345.com.example.lite, components: [ { /: /share/*, ?: { client: lite* }, exclude: false } ] } ] } }这个方案的坑在于query 参数的顺序敏感。?clientmainfromwx和?fromwxclientmain在苹果的匹配里可能表现不一致实测下来顺序不同会导致匹配失败。所以生成链接时一定要固定参数顺序。通配符*只能放在值的末尾不能放中间。?client*main是无效的。如果链接里没有client参数两个 App 都匹配不上直接落 Safari。所以服务端必须保证每条分享链接都带上这个参数。3.3 方案三exclude 排除法兜底用不推荐单独用exclude字段可以让某个 App 明确不响应某些路径。比如主 App 排除/lite/*极速版排除/main/*{ appID: ABCDE12345.com.example.main, components: [ { /: /lite/*, exclude: true }, { /: /*, exclude: false } ] }这个方案的逻辑是先排除再全匹配。但实测下来exclude的优先级判定在 iOS 不同版本间有差异iOS 14 和 iOS 16 的表现就不完全一样。我一般只把它当兜底不作为主要区分手段。3.4 三种方案的选型对照维度路径前缀区分Query 参数区分exclude 排除法匹配稳定性高中低服务端改动量中需改路径小加参数小历史链接兼容需重定向需补参数需重定向排查难度低中高推荐场景新项目、可改路径路径固定、可加参数仅兜底我的建议很明确新项目一律用路径前缀区分这是最不容易出问题的方案。如果路径已经固定死了改不动再考虑 query 参数但一定要做好参数顺序和通配符的处理。4. 服务端与客户端联调的完整实操链路4.1 AASA 文件的部署与验证AASA 文件必须满足几个硬性条件缺一个都会导致整个 Universal Link 失效路径必须是/.well-known/apple-app-site-association不能带.json后缀。Content-Type 必须是application/json。不能有 301/302 重定向必须是 200 直接返回。不能要求登录或鉴权。文件大小不超过 128KB未签名情况下。部署完之后用苹果官方的验证工具或者直接 curl 检查curl -I https://yourdomain.com/.well-known/apple-app-site-association重点看返回头里的Content-Type和状态码。我踩过的坑是 CDN 把.well-known目录给缓存了旧版本导致新配置一直不生效排查了半天才发现是缓存问题。所以每次改完 AASA记得刷新 CDN 缓存。4.2 Xcode 侧的 Associated Domains 配置两个 App 的 Xcode 工程里都要配置 Associated Domains。在 Signing Capabilities 里添加applinks:yourdomain.com注意这里不要带https://前缀也不要带路径只写域名。如果要支持子域名可以写applinks:sub.yourdomain.com。有个容易忽略的点两个 App 必须用同一个 Team ID。如果主 App 和极速版分属不同开发者账号那 AASA 里的 appID 前缀就不一样虽然理论上也能配但实测下来跨 Team 的匹配优先级判定更不稳定能避免就避免。4.3 客户端处理链接的代码逻辑App 被唤起后需要在SceneDelegate或AppDelegate里处理传入的 URL。iOS 13 之后用scene(_:continue:)func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { guard userActivity.activityType NSUserActivityTypeBrowsingWeb, let url userActivity.webpageURL else { return } // 解析路径判断是不是本 App 该处理的 let path url.path if path.hasPrefix(/main/) { handleMainShare(url: url) } else { // 不是本 App 的路径理论上不该走到这里做个兜底 openInSafari(url: url) } }这里有个实战经验一定要做路径校验兜底。虽然 AASA 配置正确的话不该本 App 处理的链接不会唤起本 App但线上环境复杂用户可能通过其他方式比如复制粘贴到 App 内触发做个校验能避免误处理。4.4 联调阶段的验证清单联调时按这个顺序验证能快速定位问题出在哪一环AASA 文件可访问性浏览器直接打开https://yourdomain.com/.well-known/apple-app-site-association能看到 JSON 内容。App 安装后是否拉取成功删除 App 重装观察控制台有没有 AASA 拉取失败的日志。链接点击测试在备忘录里粘贴链接长按看是否出现在 XXX 中打开的选项。如果出现说明系统识别到了关联。多 App 场景测试两个 App 都装上分别点击不同前缀的链接看唤起是否正确。提示iOS 对 AASA 有缓存改完配置后不是立即生效。开发阶段可以在设备上删除 App 重装来强制刷新或者用开发者模式下的Associated Domains Development开关。5. 那些文档里不会写的坑与排查实录5.1 坑一两个 App 都装时链接随机唤起这是最典型的问题。根因就是两个 App 的匹配条件有重叠系统无法判定优先级。排查方法是逐条对比两个 App 的 AASA 配置看有没有路径或参数的交集。我遇到过一个隐蔽的情况主 App 配了/share/*极速版配了/share/*但加了exclude某个子路径。表面看极速版排除了部分路径但剩下的路径还是和主 App 重叠结果就是重叠部分随机唤起。解决办法就是让两个 App 的匹配条件完全互斥不留任何交集。5.2 坑二query 参数顺序导致匹配失败前面提过components的 query 匹配对参数顺序敏感。我实测过一组数据链接配置结果?clientmainfromwx?clientmain*匹配成功?fromwxclientmain?clientmain*匹配失败?clientmain?clientmain*匹配成功所以服务端生成链接时必须固定参数顺序把用于匹配的参数放在最前面。这个规则苹果文档里没明说是实测出来的。5.3 坑三AASA 更新后老用户不生效AASA 的更新不是实时的。iOS 会在特定时机拉取比如 App 安装、系统更新、或者苹果认为需要刷新的时候。老用户可能几天甚至几周都用的是旧配置。应对办法有两个一是服务端做兼容新老配置的路径都支持通过重定向过渡二是引导用户更新 App新版本 App 安装时会重新拉取 AASA。我一般两个一起用服务端兼容保底App 更新加速。5.4 坑四CDN 和反向代理的干扰AASA 文件经过 CDN 或 Nginx 反向代理时容易出现 Content-Type 被改写、路径被重写、或者返回了缓存的情况。排查时直接用 curl 打源站和打 CDN 各一次对比返回头。Nginx 的配置参考location /.well-known/apple-app-site-association { default_type application/json; add_header Cache-Control no-cache; alias /path/to/apple-app-site-association; }关键是default_type application/json和禁用缓存。CDN 侧要把.well-known目录加入不缓存名单。5.5 坑五iOS 版本差异导致的匹配行为不一致iOS 13、14、15、16 在 Universal Link 的匹配细节上有差异。比如components的 query 通配在 iOS 13 上支持不完整iOS 14 之后才稳定。如果 App 要支持 iOS 13建议用路径前缀方案别用 query 参数。我的做法是维护一个版本兼容矩阵记录每个方案在各 iOS 版本上的实测表现新方案上线前先在各个版本的真机上跑一遍。这个矩阵是团队内部积累的比任何文档都靠谱。6. 多 App 矩阵下的长期维护建议6.1 把 AASA 配置纳入版本管理AASA 文件不要手动改纳入 Git 管理每次改动走 Code Review。因为一个字符的错误就可能导致整个 Universal Link 失效人工改太容易出错。我见过有人把appID里的 Team ID 写错一位排查了一整天才发现。6.2 建立自动化验证脚本写个脚本每次 AASA 部署后自动验证#!/bin/bash URLhttps://yourdomain.com/.well-known/apple-app-site-association CONTENT_TYPE$(curl -sI $URL | grep -i content-type) STATUS$(curl -s -o /dev/null -w %{http_code} $URL) if [[ $STATUS ! 200 ]]; then echo FAIL: status is $STATUS exit 1 fi if [[ $CONTENT_TYPE ! *application/json* ]]; then echo FAIL: content-type is $CONTENT_TYPE exit 1 fi echo PASS这个脚本挂到 CI 里每次部署自动跑能挡掉大部分低级错误。6.3 新增客户端时的检查清单每次新增一个客户端 App按这个清单过一遍新 App 的 Bundle ID 是否已加入 AASA 的details数组。新 App 的匹配路径是否与现有 App 完全互斥。新 App 的 Xcode Associated Domains 是否配置正确。服务端生成链接的逻辑是否已支持新客户端的前缀或参数。历史链接是否需要重定向兼容。各 iOS 版本真机测试是否通过。这套流程跑顺了多 App 矩阵的 Universal Link 维护就不再是玄学问题而是可预期、可验证的工程问题。6.4 一个容易被忽略的细节App 卸载重装后的行为用户卸载 App 再重装AASA 会重新拉取这本来是好事。但如果用户在卸载期间点击了分享链接链接会落到 SafariSafari 里可能引导去 App Store。用户装完 App 后之前那条链接不会自动唤起 App需要用户重新点击。这个体验断点没法完全消除但可以在 Safari 落地页做个提示已安装点击这里重新打开用 JS 尝试唤起提升转化。这个细节在分享裂变场景里影响挺大尤其是邀请奖励类的功能用户装完 App 发现没拿到奖励容易流失。我的做法是在落地页存一个 cookie记录用户是从哪条链接来的App 首次启动时通过剪贴板或者服务端接口把归因补上。虽然苹果对剪贴板的限制越来越严但服务端归因这条路一直有效。7. 关于匹配优先级的一个反直觉结论最后分享一个我实测下来觉得挺反直觉的点在匹配条件完全相同时先安装的 App 并不总是赢。我做过一组对照实验在同一台设备上先装主 App 再装极速版和先装极速版再装主 App点击同一条无区分参数的链接唤起结果并不稳定遵循先装先赢。有时候系统会唤起后装的有时候唤起先装的甚至同一台设备不同时间点结果都不一样。这说明苹果的匹配在条件相同时底层可能还依赖一些我们无法控制的缓存或索引状态。所以不要试图依赖安装顺序来区分客户端这是不可靠的。唯一可靠的做法就是让匹配条件互斥让系统没有歧义可判。这也是我为什么一直强调路径前缀方案的原因——它把该唤起谁这个问题在配置层面就解决掉了不留给系统去猜。如果你现在正被多客户端共用链接的问题困扰先别急着调代码回去把两个 App 的 AASA 配置逐字对比一遍看看匹配条件有没有交集。十有八九问题就出在那里。