前阵子赶版本市场那边丢过来一句很直接的话信息流买量的落地页上用户手机里已经装了我们的游戏包但点链接进去还是先开网页、再引导下载流失一大截——能不能做到点链接直接拉起游戏并且进到指定的活动页面。这个需求说白了就是手游最常见的 Deep Link 唤醒链路。放到 iOS 端从 URL Scheme 到 Universal Links从 Xcode 的 Associated Domains 到服务器上的 AASA 文件再到 Unity 的 C# 层把参数接住、分发给业务完整跑通一趟并不轻松。这篇文章把我实际落地这套流程的方案、代码骨架和踩过的坑整理出来给正在接类似唤醒进游戏需求的 Unity 客户端同学一条可以直接照抄的路线。1. 从买量需求到 Deep Link手游为什么要做这套唤醒链路1.1 业务场景点击链接后用户到底走了哪条路我们先站在产品和运营的角度看这个问题。手游的流量来源里网页链接依然占了大头信息流广告、短信营销、KOL 分享、玩家拉新返利、社群礼包……用户都是在浏览器或微信里先看到一条链接然后被引导去打开游戏。没有 Deep Link 的时候这条路径是用户点击链接 - 打开 H5 落地页 - 落地页判断设备里有 App后弹提示 - 用户手动切到游戏 - 游戏冷启动进入主界面 - 用户自己去找礼包、活动入口。这条路上每一步都在流失。广告行业有个普遍说法从点击到真正进入游戏内目标页面每多一步至少折损 10% 到 20% 的人。尤其手动去主界面找入口这一步很多玩家根本没有耐心直接关掉了。而 Deep Link 做通之后路径变成用户点击链接 - iOS 系统识别链接属于我们 App - 直接拉起游戏进程 - 游戏启动后读取链接携带的参数 - 创建角色/进入活动页/自动发包。中间的 H5 落地页、跳转提示、手动切换、手动找入口全部被干掉了。这个体验差距对买量转化率是决定性的。我们当时几次投放对比下来支持 Deep Link 的渠道点击进游戏率比纯落地页跳转高了三成左右数据相当可观。1.2 链路拆解一个 Deep Link 从点击到游戏内响应经过哪些环节把整条链路拆开其实包含四段独立的工程链接入口段链接 URL 长什么样路径上带哪些业务参数活动 ID、渠道码、邀请人 ID、礼包码等。这是产品和客户端提前约定好的协议。系统唤起源iOS 如何识别这条链接属于我们 App。这里就是标题里提到的 URL Scheme 和 Universal Links 两套机制。原生到 Unity 的数据桥接段iOS 原生层收到 URL 之后用 Objective-C 处理、缓存再传给 Unity 的 C# 层。这里要解决的核心问题是Unity 进程还没起来时数据怎么办。C# 业务分发段Unity 里有一个常驻的 DeepLinkManager接收参数、解析参数、等游戏场景准备好了再把参数广播给业务模块。之前很多团队卡在第 2、3 段之间Xcode 里配了 URL Scheme网页跳到 App 没问题但参数到了原生层就断了——Unity 侧收不到或者冷启动时参数直接丢了。这篇文章的重点就是把这四段完整串起来。补一句如果你是 iOS 原生开发出身平时主要处理证书配置到上架的流程那这套 Deep Link 配置是你必然要跨的另一道坎如果你是 Unity 开发者原生的 AppDelegate 代码你可能不太熟但不用怕后面的 OC 代码量非常少核心逻辑还是 C# 侧。2. URL Scheme 与 Universal Links两代方案的技术对比与选型2.1 URL Scheme初始化简单但唤醒体验有明显短板URL Scheme 是 iOS 最早提供的深度链接方案原理很简单在 App 的 Info.plist 里注册一个自定义协议比如mygame://open?pagegift然后 iOS 发现系统里某个 App 注册过这个协议就在用户点击链接时把这个 URL 直接丢给对应 App 处理。它的优点是实现成本极低。Xcode 里在 URL Types 填一个 schemeAppDelegate 里实现application:openURL:options:就能收参数。Unity 工程里甚至只需要在Assets/Plugins/iOS放一个很小的 OC 文件就行不用动服务器。但短板非常致命跳转弹窗系统会弹在 Safari 中打开『某某 App』吗多一步确认iOS 9 之后尤其在 Safari 里点 scheme 链接弹窗特别明显。设备未安装时完全无助用户手机上没装 App点击mygame://会直接报错无法打开没有网页可以兜底。买量场景里大量用户是未安装的这条直接把新用户转化路堵死了。容易被劫持理论上任何 App 都能注册相同的 scheme系统只按注册关系转发不校验应用归属。网页侧无法感知H5 页面没法通过 JS 可靠判断 scheme 能不能唤起成功导致已安装跳 App、未安装跳商店这种动态分流很难做。所以现在的主流做法里URL Scheme 一般是作为App 内互相跳转和兼容老版本的兜底方案不再承担网页到 App 的主入口职责。2.2 Universal Links把链接变成真正的网页地址Universal Links 是 iOS 9 引入的方案核心思想是不再用自定义协议而是直接用https://正常网址作为唤醒入口。系统会做这样几步处理用户点击https://yourdomain.com/open?pagegift只要设备上装了声明了该域名关联的 AppiOS 就自动把链接交给 App。iOS 判断这个域名是否属于这个 App靠的不是本地配置而是去请求服务器上固定的一个 JSON 文件apple-app-site-association简称 AASA。如果设备没装 App链接正常在 Safari 中打开就是普通网页可以通过落地页继续做下载引导。这套机制解决了 URL Scheme 最重要的三个痛点没有确认弹窗iOS 13 之前、未安装时能正常打开网页兜底、域名归属校验安全。对于买量、分享回流这种已装拉活、未装引下载的场景Universal Links 几乎是唯一正确选择。它的代价是要同时配置三样东西App 的 entitlements含 Associated Domains、服务器上的 AASA 文件、HTTPS 证书。后两个对于 Unity 团队来说往往不是自己熟悉的领域这也是很多团队被卡住的地方。补充一个重要细节从 iOS 13 开始用户首次点击 Universal Links 时系统会弹一次是否打开 App的确认窗口用户选择打开后才会记住偏好。这个和旧版本无感跳转的体验不同你在测试和引导文案里要留意但整体上它依然是网页到 App 的第一推荐方案。2.3 手游方案选型建议Universal Links 为主URL Scheme 兜底直接说结论手游 iOS 端应该把 Universal Links 作为完整的正式方案URL Scheme 继续保留但只作兜底。我建议的双通道策略是这样的通道作用配置位置Universal Links网页/短信/系统浏览器到 App 的主入口承担 90% 以上拉活量Xcode Associated Domains 服务器 AASAURL Scheme老版本兼容、App 内部及部分第三方 App 间跳转、某些不支持 UL 的内置浏览器兜底Info.plist URL Types两者并存原生层统一把 URL 转成来源 原始串发给 C#C# 不关心来源DeepLinkManager 统一收口实际业务里微信内置浏览器对 Universal Links 支持时好时坏有时会拦截跳转这种情况下先在 Web 端引导用户在浏览器打开再用 Universal Links 完成唤醒而 iOS 自带 Safari、备忘录扫一扫、短信链接基本都是 UL 直通的。所以双通道不是叠加工作量而是为不同流量渠道备好不同入口。另外注意一点AASA 文件里配置的路径一定会优先于纯 URL Scheme 参数被业务接受。因为用户看到的链接永远是https://而不是mygame://后者现在只存在于 Native 和 Native 之间跳转的场景。3. Unity 工程侧准备iOS 原生桥接与参数缓存层3.1 Unity 与 iOS 原生通信的两条通道先讲清楚一个很多 Unity 新手困惑的点Unity 构建到 iOS 后生成的 Xcode 工程里有一个UnityFrameworkUnity 的 C# 代码编译后跑在里面我们的游戏主流程是 C# 的。而 iOS 的系统回调比如收到 Universal Links是 Objective-C 层的事件发生在 Unity 的 AppController 里。两边要通信靠的是 Unity 提供的两个机制C# 调 OC用[DllImport(__Internal)] extern声明原生函数函数必须用extern C导出。用于 C# 主动去原生拉数据。OC 调 C#调用UnitySendMessage(GameObjectName, MethodName, message)。用于原生主动给 C# 发消息但前提是 C# 那边那个 GameObject 和挂载的脚本方法必须存在。注意UnitySendMessage的第二个参数是方法名方法必须是挂在该 GameObject 上某个 MonoBehaviour 的 public 方法而且不能是静态方法。第三个参数是字符串按 UTF-8 传。这两条通道配合起来就能完成深度链接参数投递的核心数据流了。我会把整体方案设计成原生先缓存 C# 主动拉取为主原生主动推送为辅——这是为了彻底解决冷启动时序问题第 5 章会展开讲。3.2 原生层处理打开链接的关键代码新建一个 OC 文件放到Assets/Plugins/iOS比如叫DeepLinkBridge.mm构建 Xcode 工程时 Unity 会自动把它编进去。先给出完整代码骨架#import UnityAppController.h #import DeepLinkBridge.h extern bool UnityIsReady; static NSString *pendingDeepLink nil; implementation DeepLinkBridge // 保存待处理的链接已在 Unity 运行时则立即通知 (void)storeDeepLink:(NSURL *)url { if (url nil) return; NSString *urlString [url absoluteString]; NSLog([DeepLink] received url: %, urlString); // 1. 先持久化保证 Unity 冷启动后可以主动拉取 NSUserDefaults *defaults [NSUserDefaults standardUserDefaults]; [defaults setObject:urlString forKey:PendingDeepLink]; [defaults synchronize]; // 2. 如果 Unity 已经就绪立刻走 UnitySendMessage 主动推送 if (UnityIsReady) { UnitySendMessage(DeepLinkManager, OnNativeDeepLink, [urlString UTF8String]); } } // 供 C# 主动拉取最后一条待处理链接 (NSString *)getPendingDeepLink { NSString *saved [[NSUserDefaults standardUserDefaults] stringForKey:PendingDeepLink]; if (saved.length 0) { [[NSUserDefaults standardUserDefaults] removeObjectForKey:PendingDeepLink]; } return saved; } end然后在 AppDelegate 里接系统回调。因为 Unity 项目的 AppDelegate 已经被 Unity 的UnityAppController接管了最稳妥的方式是新建一个DeepLinkAppDelegate.mm在application:didFinishLaunchingWithOptions:里把系统回调转发给我们的 Bridge#import UnityAppController.h #import DeepLinkBridge.h interface DeepLinkAppDelegate : UnityAppController end implementation DeepLinkAppDelegate - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *))restorationHandler { if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) { [DeepLinkBridge storeDeepLink:userActivity.webpageURL]; return YES; } return [super application:application continueUserActivity:userActivity restorationHandler:restorationHandler]; } - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionaryUIApplicationOpenURLOptionsKey, id *)options { [DeepLinkBridge storeDeepLink:url]; return YES; } - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // 处理通过 scheme 冷启动的情况 NSURL *url launchOptions[UIApplicationLaunchOptionsURLKey]; if (url) { [DeepLinkBridge storeDeepLink:url]; } [super application:application didFinishLaunchingWithOptions:launchOptions]; return YES; } endcontinueUserActivity:对应 Universal LinksopenURL:对应 URL SchemedidFinishLaunchingWithOptions:里的launchOptions[UIApplicationLaunchOptionsURLKey]处理的是 App 被 scheme 直接冷启动的情况。3.3 参数缓存为什么一定要先存 NSUserDefaults 再谈通知我见过很多第一次接 Deep Link 的同学只写了UnitySendMessage结果就是冷启动时参数神秘丢失。原因是这样用户点击 Universal Links 时如果是冷启动系统先拉起 App 进程UIApplication 的 delegate 方法被调用的时候Unity 引擎可能还在初始化C# 的脚本对象比如我们的 DeepLinkManager根本还不存在。这时候UnitySendMessage发出去消息会直接丢弃等 C# 启动起来整条数据已经没了。所以原生层正确的做法是先写入 NSUserDefaults 做持久化再判断 Unity 是否就绪来实时推送。C# 那边启动后第一件事就是主动调用原生接口把缓存的链接拉回来。这样无论在哪个启动状态下数据都不会丢。这一步的代价几乎为零但能让后面 C# 层的逻辑彻底摆脱时序地狱。记住这个原则Native 只负责收、存、尽可能 PushC# 负责拉、解析、分发。后面所有环节都好处理。4. Universal Links 完整配置链路AASA 文件与 Xcode 关联域4.1 服务端 AASA 文件的格式与部署服务器上要放一个 JSON 文件路径固定是两个之一推荐用.well-knownhttps://你的域名/.well-known/apple-app-site-associationhttps://你的域名/apple-app-site-association最小可用的 AASA 文件长这样{ applinks: { details: [ { appIDs: [ABCDE12345.com.yourcompany.yourgame], paths: [*] } ] } }解释几个字段appIDs格式是TeamID.BundleID。Team ID 在 Apple Developer 后台的 Membership 页能查到是一串 10 位大写字母数字Bundle ID 必须和 Xcode 里的一致。这里大小写、标点一个都不能错错了就直接失效。paths定义哪些路径会触发唤起。*表示全路径最简单更精细可以写/open/*只对/open/下的链接生效也可以搭配#写排除规则。推荐用components字段配合/做更清晰的路径匹配但paths足够覆盖绝大多数场景。applinks后面也可以挂smartAppBanner、spotlight等能力Deep Link 不涉及忽略即可。部署时要注意几点这些都是真机验证失败的高发原因响应头必须是application/json尤其用 Nginx 或 CDN 时要确认没有把.json的 MIME 类型配置掉。有些 CDN 默认不认识无扩展名的路径会返回application/octet-streamiOS 会直接拉取失败。内容大小尽量控制在 128KB 以内Apple 文档虽然没写死但过大容易在部分网络环境拉取超时手机端拿不到文件就等于没配。必须走 HTTPS 且证书链完整自签名证书、过期证书、证书链缺中间证书都会被拒绝。如果用了免费证书注意把中间证书也一并配到服务器上。4.2 Xcode 侧 Associated Domains 配置在 Unity 导出的 Xcode 工程里选中 Target - Signing Capabilities - 添加Associated Domains能力然后在 Domains 里写applinks:yourdomain.com注意这里不要带 https:// 前缀也不要加路径。多个域名一行一个。写完这个之后Xcode 会生成一个.entitlements文件里面内容类似keycom.apple.developer.associated-domains/key array stringapplinks:yourdomain.com/string /array这块有个 Unity 工程里的自动化技巧如果你不想每次构建 Xcode 工程都手动点一遍 Capabilities可以直接在 Unity 工程里创建一个.entitlements文件放到Assets/Plugins/iOS目录然后用自定义的IPostProcessBuild脚本在构建后自动把它拷贝进 Xcode 工程。不过考虑到 Capabilities 一般只在环境初始化时配一次且手动点一遍也就十几秒大部分团队手动操作更省事。我个人的建议是首次先手动配置跑通再做自动化减少排障变量。4.3 校验手段上线前必须过一遍的四个检查配置完之后不要急着真机测试先按顺序做四个检查能砍掉一半排障时间服务器侧 curl 检查curl -s -i https://yourdomain.com/.well-known/apple-app-site-association看返回码是否 200、Content-Type 是否为application/json、JSON 内容是否符合预期。顺手再测一下根路径版本/apple-app-site-association两个地址都通才稳。AASA 校验工具网上搜 AASA validator把域名输进去工具会模拟 Apple 的拉取过程并提示格式问题。我用过 Branch 的验证器能比较清楚地看到错误定位缺点是域名如果带国内 CDN 链路可能测试节点不通不作为唯一判断依据。Xcode 工程确认打开 Xcode确认 Associated Domains 能力存在、entitlements 里applinks:后域名与服务器域名一致。域名不能有大小写问题也不能带路径。本机 HTTPS 信任链检查用openssl s_client -connect yourdomain.com:443 -servername yourdomain.com看证书链是否完整。这个命令对不熟的同学稍微有点劝退但真机报未能打开链接时它是最快的判断入口。这四步里我最常被问到的是为什么 AASA 文件没问题、Xcode 配置也对了但真机就是不唤起。十有八九卡在证书链或 CDN 的旧缓存上。AASA 文件更新后 iOS 端有缓存通常要等一段时间有时长达一天测试环境急了可以换个没点过链接的 iPhone 再试比清缓存快得多。5. C# 层参数投递全链路从原生回调到场景消费5.1 DeepLinkManager双通道接收与待消费队列C# 这边的核心类叫DeepLinkManager是一个挂在常驻 GameObject 上的单例比如挂在一个名为DeepLinkManager的空物体上。它同时负责两条接收通道被动接收原生层在 Unity 已就绪时调用UnitySendMessage(DeepLinkManager, OnNativeDeepLink, urlString)对应 C# 的public void OnNativeDeepLink(string payload)。主动拉取C# 启动后调用原生的getPendingDeepLink把热启动期间或启动前缓存的链接拉回来。代码骨架如下using System; using System.Collections; using System.Collections.Generic; using System.Runtime.InteropServices; using UnityEngine; public class DeepLinkManager : MonoBehaviour { public static DeepLinkManager Instance { get; private set; } private readonly Queuestring _pendingQueue new Queuestring(); private bool _isReady; public event Actionstring OnDeepLinkReceived; #if UNITY_IOS !UNITY_EDITOR [DllImport(__Internal)] private static extern string getPendingDeepLink(); #endif private void Awake() { if (Instance ! null Instance ! this) { Destroy(gameObject); return; } Instance this; DontDestroyOnLoad(gameObject); } private IEnumerator Start() { // 等第一帧结束后再标记就绪避免场景内其他脚本初始化顺序问题 yield return null; _isReady true; #if UNITY_IOS !UNITY_EDITOR var pending getPendingDeepLink(); if (!string.IsNullOrEmpty(pending)) { EnqueueDeepLink(pending); } #endif ProcessQueue(); } // 原生层 UnitySendMessage 会直接调用这个方法 public void OnNativeDeepLink(string payload) { if (string.IsNullOrEmpty(payload)) return; EnqueueDeepLink(payload); } public void EnqueueDeepLink(string payload) { _pendingQueue.Enqueue(payload); ProcessQueue(); } private void ProcessQueue() { if (!_isReady) return; while (_pendingQueue.Count 0) { var payload _pendingQueue.Dequeue(); OnDeepLinkReceived?.Invoke(payload); } } }为什么要加_pendingQueue而不是收到就立刻广播因为业务模块不一定准备好了。比如游戏还在加载 AssetBundle活动页面脚本还没被实例化这时候把参数丢出去没人接。队列化之后等业务侧各自注册监听再由业务侧决定把参数取走消费就灵活得多。UnitySendMessage对应的 GameObject 名和脚本方法名要求严格一致。这里我建议保持 GameObejct 名就是DeepLinkManager方法名就是OnNativeDeepLink不要用中文路径也不要有多余空格否则原生层调用会静默失败。5.2 参数解析与业务分发链接到了OnDeepLinkReceived之后一般会有一个统一的解析入口。我习惯在DeepLinkManager里把原始 URL 字符串解码成字典再交给业务模块public static class DeepLinkParser { public static Dictionarystring, string ParseUrl(string url) { var result new Dictionarystring, string(); if (string.IsNullOrEmpty(url)) return result; Uri uri; if (!Uri.TryCreate(url, UriKind.Absolute, out uri)) return result; foreach (var pair in uri.Query.TrimStart(?).Split()) { if (string.IsNullOrEmpty(pair)) continue; var kv pair.Split(new char[] { }, 2); if (kv.Length 2) { var key Uri.UnescapeDataString(kv[0]); var value Uri.UnescapeDataString(kv[1]); result[key] value; } } return result; } }使用示例如下OnDeepLinkReceived payload { var query DeepLinkParser.ParseUrl(payload); var page query.GetValueOrDefault(page, ); var id query.GetValueOrDefault(id, ); var channel query.GetValueOrDefault(channel, ); Debug.Log($[DeepLink] page{page} id{id} channel{channel}); // 根据 page 分发到对应业务模块 if (page gift) GameService.OpenGiftPanel(id, channel); else if (page activity) ActivityModule.OpenActivity(id); };这里有个很容易被忽略的坑URL 里号在标准 query 中会被解析成空格如果参数值是 Base64 编码的字符串比如带签名的邀请码最好把 Base64 里可能出现的统一换成-和_或者在服务端生成链接时先做 URLEncode。我建议从源头约定链接参数一律使用 URLEncode客户端拿到的原始串先 UnescapeDataString 再做 Base64 解码双保险。链接格式建议统一为https://yourdomain.com/open?pagegiftid10001channelwechatinvitexxx路径前缀/open和 query 参数完全由服务端和客户端业务约定跟 Universal Links 的系统校验互相独立。AASA 里paths写的*或/open/*只管要不要唤起 App唤起之后 URL 里的所有内容都原样交给客户端。5.3 冷启动、热启动、后台唤醒三种状态的处理差异这里展开讲最核心的三种运行时状态因为很多测试只测了热启动上线后冷启动翻车冷启动用户没开过 App点击 Universal Links系统直接拉起 App 进程。此时 Unity 还没初始化UnitySendMessage不可用数据靠 NSUserDefaults 持久化。C# 侧getPendingDeepLink()主动拉取把数据取回后进队列。热启动App 正在前台运行点击 Universal Links。此时UnitySendMessage可用C# 的OnNativeDeepLink被原生主动调用数据直接进队列。后台唤醒App 在后台挂起点击链接。系统唤醒 App 并调用continueUserActivity:此时 Unity 很可能已经就绪走UnitySendMessage推送保险起见原生层依然先写缓存C# 下次启动时也能兜底。三种状态用同一套队列 就绪标记逻辑就能统一吃掉。这也是我上一节强调原生先缓存再 Push的原因哪怕UnitySendMessage推丢了C# 主动拉也能拿回来。一个细节NSUserDefaults里存的链接没有过期机制如果用户在链接被保存后很久才第一次启动 App可能会消费到非常旧的链接。我建议在 C# 侧拉取时顺手记录时间超过比如 24 小时的链接直接丢弃避免玩家再次打开游戏时被旧链接弹一个莫名其妙的活动页。6. 真机测试工具、步骤与容易被忽略的验证场景6.1 测试前准备AASA 与环境的确认真机测试之前先把环境确认做好不然很容易明明配置没问题就是唤起不了来回折腾浪费时间。准备一台iOS 真机版本尽量贴近你的目标用户群体iOS 15/16/17 都要覆盖一台。Universal Links 在不同大版本上的弹窗和行为略有差异。真机设置 - 开发者或 Xcode - Device 里确认设备能被 Xcode 识别这样待会儿能看 Console 日志。先用 Safari 打开你的 AASA 文件地址确认能正常显示 JSON 内容。这一步基本能排除服务器配置问题。如果 App 是从 TestFlight 或 Debug 构建安装的确认 Bundle ID 和 entitlements 里的一致避免测了半天发现装的是另一个签名的包。测试链接的构造我习惯写一个最小参数集方便一眼看出参数有没有穿到 C#https://yourdomain.com/open?pagetestid123channelsafari6.2 各状态下的验证步骤冷启动 Safari 直连把 App 完全杀掉上滑退出在 Safari 地址栏输入上面的链接回车。预期App 被拉起C# 的 Debug.Log 在 Console 里打出一条pagetest id123 channelsafari。这条通过说明 NSUserDefaults 缓存和主动拉取链路没问题。热启动App 切到后台不杀进程回 Safari 再次点击链接。预期App 回到前台并输出同样日志。这条通过说明UnitySendMessage推送链路没问题。后台唤醒App 切到后台过一小会儿让系统把进程挂起来再点链接重点看有没有异常弹窗或日志丢失。未安装场景把 App 卸载然后点链接。预期不再唤起而是直接打开 Safari 里的落地页。如果落地页能正常加载且能引到 App Store/TAP说明 H5 兜底生效。URL Scheme 兼容用另一个支持自定义 scheme 的测试页或者直接在 Safari 输入yourgame://open?pagetest验证 scheme 通道仍能收到参数。每一条链路我建议都用Xcode Console 日志辅助观察在 Console 里过滤applinks能看到系统请求 AASA 文件的状态码。比如状态码 404 说明服务器文件拉取失败状态码 200 但行为异常就要检查文件内容是否被 CDN 篡改。6.3 测试中常见的假成功和假失败测试过程中有几种现象很容易误导判断假成功之一在 App 已经打开甚至正在看活动页的情况下测试链接发现页面没问题就认为 Deep Link 通了。这实际是App 本来就在前台的假象冷启动链路根本没过。冷启动测试必须彻底杀掉进程。假成功之二参数在原生层打出来了C# 侧Debug.Log没打但业务上活动页恰好是默认打开的看起来像成功。一定要用带参数的链接让开出来的页面带着你传入的 ID否则这项等于没测。假失败之一AASA 文件更新后在旧设备上一直不生效以为配置错了。实际上 iOS 对 AASA 有缓存最长可能一两天。换个没点过的设备或重装 App 即可立即验证。假失败之二微信内置浏览器里点了没反应以为是 Universal Links 配置错。微信对 Universal Links 有独立限制部分版本会拦截跳转不等于你的配置有问题。要学会区分微信壳内和真实 Safari两种环境。真机测试最少做两轮一轮用测试包Debug一轮用实际分发的包TestFlight 或 Release。Release 包的 entitlements 如果用了自动化脚本注入很容易在最后一步把 Associated Domains 带丢不用真实包测一轮等于白配。7. 踩坑实录七类高频问题与完整排查思路7.1 七类高频坑位第一坑Team ID 与 Bundle ID 写错大小写。AASA 里appIDs的 Team ID 是大写字母数字Bundle ID 完全匹配 Xcode 的 Target 设置中间用点分隔没有任何空格。这类错误 curl 看不出来校验工具能报但最容易的直接表现就是 iOS 拉取成功后依然不唤起。我建议把 AASA 里的 appID 原样贴在 Xcode 工程的General - Identity旁边比对一遍。第二坑CDN 缓存导致 AASA 更新不生效。国内许多团队会把 AASA 放在 CDN 后面CDN 对无扩展名文件有时默认缓存策略异常或者返回了 404 缓存。排查时先curl -sI看Age头或X-Cache头再考虑要不要在测试域名上绕过 CDN 直连源站。第三坑URL 参数编码不统一。服务端可能直接把中文放进 query客户端如果不做Uri.UnescapeDataString拿到的就是一串百分号编码反过来服务端已经 Encode 过客户端又 Encoder 一次数据就双重编码了。这块必须在联调文档里写清楚所有 query 参数一律 URLEncode客户端统一只 Unescape 一次。第四坑冷启动参数丢失。原因是只做了UnitySendMessage没做 NSUserDefaults 缓存或缓存了但 C# 侧没主动拉取。检查方法原生层打日志看收到链接的一瞬间 UnityIsReady 是否为 falseC# 侧打印启动拉取结果。第五坑场景未加载时参数被ProcessQueue直接吞掉。比如_pendingQueue有值但业务模块还没注册完监听队列一处理消息就没了。所以我在代码里特意让Start里先yield return null再拉取和处理并且把OnDeepLinkReceived事件设计成可以随时订阅业务模块晚了也能拿到事件。如果你的业务场景是晚注册的模块也要能收到早期参数可以改成缓存值 新注册者立即获得最后一次参数的模式。第六坑微信环境不唤起被误判为配置失败。微信内置浏览器对 Universal Links 有独立限制甚至会出现点击无反应或者跳到空白页这不是你配置错了。正规做法是在 H5 落地页上引导用户点右上角在浏览器打开再走一次 Universal Links。第七坑多个应用共享同一个关联域名时互相干扰。AASA 里 appIDs 可以写多个但每个 app 的关联域是独立的。曾经遇到过一个团队配置了同域名的 App A 和 App B结果 A 的 AASA 文件里把两个 appID 都写了用户点击链接后系统把链接随机判给了其中一个 App。一个 App 的 AASA 文件里只写自己的 appID共享域名场景各拉各的文件。7.2 从链接到 C# 的完整排查链路如果问题还是复现不了我建议按下面这条链路逐层排查每一层都有明确的通过/不通过信号不用瞎猜确定链接本身正确在 Safari 里打开链接确认 URL 是你预期的那条没有 302 跳转跳到别的地址。有些服务端会做参数追加或者短链跳转跳转后的最终 URL 才是客户端收到的。确认 AASA 可达curl -s -i https://域名/.well-known/apple-app-site-association检查状态码、Content-Type、JSON 内容。如果文件在服务器上正常但curl不通基本可以锁 CDN。确认 Xcode 侧关联域存在打开 XcodeSigning Capabilities里看 Associated Domains确认applinks:前缀和域名。注意 Unity 重新构建 Xcode 工程可能会覆盖配置每次重新 Build 后都检查一次。确认系统真的请求了 AASA连上 Xcode打开 Console过滤关键词applinks或你的域名点一次链接看是否有Server fetched、URL等日志。没有日志基本等于系统认为该链接与 App 无关回到步骤 2、3。确认原生层收到了 URL在storeDeepLink:里打 NSLog看链接是否进了原生层。没进就说明系统碍于弹窗或用户设置没把链接派给 App换了测试设备再试。确认 C# 收到了参数在OnNativeDeepLink和getPendingDeepLink()返回处各打一条 Log。如果原生有、C# 没有检查 GameObject 名和方法名是否匹配UnitySendMessage的参数。确认业务模块消费了参数检查OnDeepLinkReceived事件有没有订阅者、ProcessQueue是否被_isReady挡住了。这套链路走下来99% 的问题都能定位到具体的某一层。其实 Deep Link 本身逻辑不复杂真正麻烦的是它横跨服务器、Xcode 原生、Unity 三块每一个环节的失误都表现为点链接没反应。但只要按链路逐层确认很快就能找到断点。最后再分享一个我自己的习惯把这套 Deep Link 的 AASA 文件、Xcode entitlements、原生 Bridge、C# Manager 四个部分都放进 Unity 工程的Assets/Plugins/iOS和Assets/Scripts/DeepLink目录连同部署校验命令写成一个 README 文档。以后新项目接买量、接群分享、接内嵌 H5 活动页的时候直接照文档跑一遍半小时就能把这条链路搭完。这种需求在手游生命周期里会遇到很多次值得一次性做好成通用基础能力。