macOS多应用共用Universal Link异常问题求助

问题背景 #

为两个macOS应用配置了同一域名的Universal Link，apple-app-site-association文件配置如下：

{
"applinks":{
   "apps":[],
     "details":[
        {
           "appID":"E5R4JF6D5K.com.demo.App1",
           "paths":[
                "/app1/*"
            ]
        },
        {
          "appID":"E5R4JF6D5K.world.demo.App2",
          "paths":[
              "/app2/*"
           ]
         }
      ]
   }
}

部署后仅App1能被正常唤起，访问http://custom.com/app2/...跳转至浏览器；卸载App1后所有链接均跳转至浏览器。单独配置不同域名时功能正常。

排查步骤 #

1. 验证App2的关联域与配置文件一致性

• 确认App2的Associated Domains entitlement已添加applinks:custom.com，注意大小写和无多余空格，macOS对该配置的格式要求严格。
• 检查App2的Provisioning Profile是否包含该entitlement：在Xcode中选择App2目标，进入Signing & Capabilities，刷新Provisioning Profile，确保关联域配置已被正确包含。

2. 检查apple-app-site-association文件的有效性

• 验证JSON语法：确保文件无语法错误（如缺失逗号、括号不闭合），可通过本地JSON校验工具检查。
• 确认文件编码与响应头：文件必须为无BOM的UTF-8格式，服务器返回的Content-Type头必须是application/json（而非text/plain）。可通过终端命令验证：

  curl -I https://custom.com/apple-app-site-association
  

  查看响应头中的Content-Type字段是否符合要求。

3. 核对App2的Team ID与Bundle ID

• 确认apple-app-site-association中App2的appID格式为TeamID.BundleID，其中：
  • Team ID（E5R4JF6D5K）必须与App2开发者账号的Team ID完全一致；
  • Bundle ID（world.demo.App2）必须与App2目标的Bundle ID完全匹配，大小写敏感，不能有任何差异。

4. 清除Universal Link缓存

Apple会缓存apple-app-site-association文件及关联应用信息，缓存过期或异常可能导致问题：

• 重启Mac，清除系统缓存；
• 终端执行命令重置Spotlight索引（Universal Link依赖Spotlight缓存）：

  killall -9 coreindexd
  

• 测试时使用全新的路径（如http://custom.com/app2/new-test-path），避免旧路径的缓存影响。

5. 检查App2的Universal Link回调实现

• 确认App2的application(_:open:options:)方法（macOS下处理URL打开的回调）已正确实现，且返回true以告知系统已处理该链接。示例代码：

  func application(_ application: NSApplication, open urls: [URL], options: [NSApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
      // 处理Universal Link逻辑
      return true
  }
  

  如果该方法未实现或返回false，系统会自动 fallback 到浏览器。

6. 排查服务器路径与重定向问题

• 确认访问http://custom.com/app2/*时，服务器未进行重定向（如跳转到https或其他路径），重定向会导致Universal Link的路径匹配失效。可通过curl命令查看实际响应：

  curl -L -v http://custom.com/app2/test
  

  检查是否存在非预期的重定向行为。

内容的提问来源于stack exchange，提问作者Vipul Gupta