React Native iOS端Universal Link失效：Android、Deep Link运行正常

问题背景 #

• Android端Universal Link全流程运行正常，iOS端自定义Scheme的Deep Link可正常唤起应用
• 点击HTTPS示例链接（如https://example.com）时，链接直接在Safari中打开，无唤起对应iOS应用的跳转逻辑
• 已完成的基础配置：
  1. 服务器端托管apple-app-site-association文件，配置内容为：

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "<Team_ID>.xxx.xxxxx.xxxx.xx.xx",
                "paths": [
                    "NOT /_/*",
                    "/*"
                ]
            }
        ]
    }
}

2. AppDelegate.m中已添加RCTLinkingManager对应的两个代理方法：

- (BOOL)application:(UIApplication *)application
    openURL:(NSURL *)url
    options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [RCTLinkingManager application:application openURL:url options:options];
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity
    restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
{
    return [RCTLinkingManager application:application
                  continueUserActivity:userActivity
                    restorationHandler:restorationHandler];
}

3. Apple开发者后台已为对应App ID开启Associated Domains权限
4. 项目Entitlements中已完成Associated Domains关联配置
5. 当前项目React Native版本为v0.63.3

常见遗漏配置排查项 #

• 服务器端apple-app-site-association托管校验
  • 文件必须托管在域名根路径或者.well-known目录下，可通过HTTPS无跳转直接访问，不能设置登录校验、301/302重定向（比如强制跳转到带www的二级域名）
  • 文件响应头的Content-Type必须设置为application/json，不能是text/plain等其他类型
  • 域名HTTPS证书必须是受iOS系统信任的公网证书，无证书链缺失、自签名问题，否则系统会拒绝拉取关联配置
  • 路径匹配规则调整：iOS对通配符的匹配逻辑存在版本兼容差异，可临时将paths配置为["*"]全量匹配，排除通配符写法导致的匹配失效问题；同时注意paths数组的匹配顺序是从上到下依次生效，NOT规则必须放在通配规则之前，避免通配规则先匹配到本该排除的路径
  • 确认appID格式正确：必须为开发者团队ID.App的Bundle Identifier，不存在Bundle ID填写错误、团队ID错填为App前缀的问题
• 客户端打包配置校验
  • Associated Domains的配置格式必须为applinks:你的域名，不能添加https前缀、不能带路径，错误写法（如applinks:https://example.com）会导致配置完全不生效
  • 确认打包使用的描述文件已包含Associated Domains权限，不能仅在开发者后台开启权限，却使用未包含该权限的旧描述文件打包
  • 系统拉取配置存在延迟：测试时需先完全卸载旧版本应用，重新安装后等待1-2分钟让系统完成apple-app-site-association文件拉取，不要刚装完就直接测试
• 版本兼容与测试方式校验
  • React Native v0.63.3版本需确认RCTLinkingManager Pod依赖正确链接，无模块导入失败问题
  • 测试入口限制：不要从Safari地址栏输入链接测试，该场景不会触发Universal Link跳转逻辑；需从iMessage、备忘录、第三方App内的可点击链接入口测试，仅系统判定为外部跳转场景时才会触发Universal Link唤起
  • 长按链接校验配置生效状态：长按链接弹出操作菜单时，如果菜单中没有对应应用的打开选项，说明系统未成功拉取到关联配置；如果之前手动选择了“在Safari中打开”，系统会记忆该选择，可通过长按菜单重新选择对应应用恢复唤起逻辑
  • 测试时可检查系统开发者选项：在设置 > 开发者 > Universal Links中，确认相关调试开关处于开启状态，排除系统配置拦截的问题

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