从云端 Mac 排查 iOS Universal Links 关联文件

发布分支的商品链接在浏览器里正常，装到测试设备后却始终打开网页。此时直接改 App 的跳转代码，往往会绕过真正的故障点：设备首先要取得域名提供的关联文件，确认这个域名允许指定 App 接管相应路径。可以在云端 Mac 上先把文件交付链路查清，再让设备复测。两边的证据分开记录，比反复点击链接有效。

先固定一个失败样本

记录完整链接、预期打开的 App、实际打开方式、设备系统版本与 App 构建版本。至少准备两条链接：一条应由 App 接管，一条应保留在网页中。不要只写“所有链接都不行”；域名、路径和查询参数不同，可能命中完全不同的规则。

还要确认测试动作：从可点击的链接进入，与在浏览器地址栏手动输入网址，不是同一种验证方式。团队复测时应沿用同一个入口。若生产和预发布使用不同域名，分别建记录，不能拿一个域名的文件解释另一个域名的表现。

把“服务器现在返回什么”和“这台设备现在怎样打开链接”写成两列。前者可立即复查，后者可能受到安装状态和缓存影响。

检查文件是否直达

在云端 Mac 的终端设置团队实际控制的域名，不要把应用包标识当域名。关联文件应能从 /.well-known/apple-app-site-association 直接取得；检查时不要让命令自动跟随跳转，否则容易把跳转后的成功响应误判为文件直达。

export APP_DOMAIN='填入团队实际控制的域名'
test "$APP_DOMAIN" != '填入团队实际控制的域名' || exit 1
curl -sS -D aasa-headers.txt \
  -o aasa-body.json \
  "https://${APP_DOMAIN}/.well-known/apple-app-site-association"
cat aasa-headers.txt
wc -c aasa-body.json
plutil -lint -- aasa-body.json

确认最终 HTTP 状态为 200，没有指向登录页或其他路径的 Location，正文不是 HTML 错误页，Content-Type 为 application/json。plutil 通过只能证明语法可解析，不能证明规则正确。如果命令因网络错误退出，先查域名解析与 TLS 连通性；不要用磁盘上旧的 aasa-body.json 当作本次结果。检查期间可删除旧文件后重跑，并将响应头与正文一起留存。

不要只测一个网络入口

若文件经过缓存或反向代理，分别从团队常用网络和云端 Mac 请求同一地址，比较正文内容及响应头中的缓存信息。两个入口结果不同时，先检查发布路径、缓存键与刷新流程。不要通过放宽所有缓存规则来掩盖问题；目标是让同一域名的关联文件稳定返回预期内容。

核对标识与路径规则

找到 JSON 中 applinks.details 对应的条目，逐字核对团队标识与 App 包标识组成的 appID。再把失败样本的 URL 路径逐条代入规则。路径是否区分大小写、末尾斜杠是否存在、排除规则是否先于宽泛规则产生影响，都应以文件实际采用的规则格式逐项验证；不要凭网页路由能访问就推断 App 一定能接管。

查询参数可帮助 App 打开后定位内容，但不能替代对 URL 路径的匹配检查。若团队正在从旧版 paths 迁移到 components，先确认设备目标系统支持所采用的写法，再用实际测试链接验收；不要在没有对照用例的情况下同时改标识、规则和应用代码。

再查构建产物与设备

服务器文件正确后，核对 App 构建所用的关联域名配置。域名条目应指向实际服务该文件的主机名；子域名不能默认视为彼此等价。确认安装到设备上的确是刚检查的构建版本，而不是另一条发布分支的包。修改配置后必须重新构建并安装，单独刷新服务器文件不能改变已安装 App 的配置。

在测试设备上保留一份“修改前”记录，再安装新构建，从相同来源点击同一条链接。若服务器已返回新规则而设备仍沿用旧表现，可重新安装 App 后再测，并记录两次结果。关联文件的取得与验证不应被假设为即时完成；不要仅凭一次点击就宣称某次服务器修改无效。

按边界定位，而不是一起重试

文件拿不到或返回跳转，处理交付链路；文件能取得但标识、路径不符，处理规则或构建配置；两者都吻合而单台设备失败，再比较安装历史、设备版本与点击入口。每次只改一层，保留修改前后的响应头、文件正文、构建标识和设备观察结果，才能确认是哪项改动起了作用。

把检查纳入发布流程

可以在发布任务中增加一项轻量检查：请求正式域名的关联文件，要求无跳转、状态正确、JSON 可解析，并用一条应接管及一条不应接管的路径核对规则。自动检查只能覆盖服务器与静态配置；设备上“点击后由谁打开”仍需用安装后的构建做验收。

最后把失败样本、实际响应、匹配规则和设备复测结果放在同一张记录里。下次发生“网页能开、App 不开”时，值班同事就能从最近一次已通过的边界继续查，而不必先猜是链接代码还是缓存。

常见问题