React Native iOS Universal Link跳转至Safari而非App问题求助

一、apple-app-site-association 文件核心检查 #

• 替换占位符：把文件里的<TeamID>和<BundleID>换成真实值——TeamID是苹果开发者后台的团队ID，BundleID是Xcode项目里的Bundle Identifier，必须完全匹配，不能保留尖括号。
• 部署规范验证：
  • 文件必须命名为apple-app-site-association，不能加.json后缀。
  • 部署路径只能是域名根目录或.well-known子目录（比如https://你的域名.com/apple-app-site-association或https://你的域名.com/.well-known/apple-app-site-association）。
  • 服务器必须用苹果信任的正规HTTPS证书，不能用自签证书。
  • 检查文件的Content-Type响应头，必须是application/json，避免服务器默认返回text/plain导致解析失败。

二、Xcode 项目配置校验 #

• 开启关联域名能力：在Xcode的Signing & Capabilities中添加Associated Domains，然后添加条目applinks:你的域名.com（不需要加https前缀）。
• 匹配ID信息：Xcode里的Bundle ID、签名用的Team ID，必须和apple-app-site-association文件里的完全一致。
• URL Scheme 配置：如果测试自定义Scheme（比如yourapp://），要在Info.plist里添加CFBundleURLTypes数组，配置对应的Scheme。

三、缓存与测试问题处理 #

• 清除苹果缓存：苹果会缓存关联文件，修改后可能等24小时才生效，可手动重置：进入设置 -> Safari浏览器 -> 清除历史记录与网站数据，或直接重启设备。
• 有效测试方式：
  • 在Safari里输入你的Universal Link（比如https://你的域名.com/test），长按链接看是否有“在[你的App名]中打开”的选项，没有则说明配置未生效。
  • 用苹果官方的App Search验证工具检查文件合法性，输入域名即可查看解析结果。
• React Native 端逻辑配置：确保项目里正确监听链接事件，示例代码：

import { Linking, useEffect } from 'react-native';

useEffect(() => {
  const handleDeepLink = (event) => {
    console.log('唤起的链接:', event.url);
    // 这里写你的跳转处理逻辑
  };

  Linking.addEventListener('url', handleDeepLink);
  return () => Linking.removeEventListener('url', handleDeepLink);
}, []);

四、额外常见问题排查 #

• 子域名场景：如果用子域名，要在Associated Domains里添加applinks:子域名.你的域名.com，同时把关联文件部署到对应的子域名下。
• 路径匹配规则：当前paths: ["*"]允许所有路径，确保没有语法错误，苹果的路径匹配支持NOT前缀排除路径，但当前配置无需调整。

内容的提问来源于stack exchange，提问作者Varun Kumar