好的，在配置 Associated Domains 时，有几个关键细节需要特别注意，这些细节直接影响 Universal Link 能否正常工作。
1. ** entitlements 文件中的域名格式 **
-
必须包含
applinks:前缀plaintext
applinks:www.example.com -
不要加
https://或路径 -
子域名需要单独配置 ，比如
applinks:blog.example.com
2. Team ID 和 Bundle ID 必须正确
-
apple-app-site-association文件中的appID格式为：plaintext
<Team ID>.<Bundle Identifier> -
Team ID 在 Apple Developer 网站 查看
-
Bundle ID 在 Xcode 项目的 "Signing & Capabilities" 中确认
3. 服务器上的 apple-app-site-association 文件
-
必须放在根目录或
.well-known目录plaintext
https://www.example.com/apple-app-site-association https://www.example.com/.well-known/apple-app-site-association -
文件不能有后缀 （不是
.json） -
Content-Type 必须是
application/json -
必须支持 HTTPS，且证书有效（不能是自签名证书）
-
不能有重定向（比如 HTTP 跳转到 HTTPS 会导致验证失败）
4. paths 配置规则
-
顺序重要：Apple 会按数组顺序匹配，找到第一个匹配项就停止
-
通配符
*匹配任意字符（包括子路径） -
NOT关键字 必须放在数组第一个位置，用于排除路径json
"paths": ["NOT /admin/*", "/app/*"] -
精确匹配 ：如果路径结尾不加
*，则只匹配该路径本身
5. Xcode 项目设置
- Signing & Capabilities 中添加 Associated Domains
- 确保 entitlements 文件被正确签名
- 测试时使用 Ad Hoc 或 Development 证书（不能用 Enterprise 证书测试）
6. 测试和验证
-
使用 Apple 的 App Search API Validation Tool https://search.developer.apple.com/appsearch-validation-tool/
-
在设备上测试（模拟器可能不支持某些功能）
-
清除之前的缓存： bash
运行
defaults delete com.apple.coreservices.useractivityd -
检查是否能通过链接唤醒应用，并正确跳转到指定页面
7. 常见问题排查
- 如果链接打开了网页而不是应用，可能是：
apple-app-site-association文件配置错误- 域名或路径不匹配
- 证书或 HTTPS 配置问题
- 如果应用被唤醒但没有正确处理链接，检查：
application:continueUserActivity:restorationHandler:方法实现userActivity.webpageURL是否正确解析