Unity iOS深链接入全攻略：URL Scheme与Universal Links到C#参数投递

做手游买量和老玩家召回的同学，应该都遇到过同一个场景：投放链接、Safari 打开的 H5 页面、或者微信里的分享卡片，用户点了一下，已经安装的游戏直接唤醒，还没安装的落到下载页。这套能力在 iOS 上就是 Deep Link，入口主要是 URL Scheme 和 Universal Links，落地时最难的部分，是把链接里带的参数完整、准确地送进 Unity 的 C# 层，让业务逻辑知道用户从哪里来、要做什么。

这篇文章我会完整走一遍 Unity iOS 深链的接入流程，从 Xcode 侧配置两种入口，到 AASA 文件的部署，再到原生插件桥接和 C# 层参数投递，最后把我这些年调试中踩过的坑一次性讲清楚。适合正在接深链的 Unity 客户端开发，也适合刚接触 iOS 原生部分的跨端开发者参考。

1. 这个链路到底在解决什么问题

1.1 深链不是“打开 App”那么简单

很多第一次接深链的人会以为，深链就是把 App 拉起来而已。但实际上，业务方要的远不止“打开”这一步。

拿一个常见的买量场景举例：用户在广告平台看到了创意素材，点击后系统先跳到你的 H5 落地页，H5 判断设备上已经装过游戏，于是尝试直接唤起 App。唤起之后，游戏内部要立刻知道这次点击来自哪个渠道、哪个 campaign、哪个创意，这样用户进到游戏后看到的第一个页面、用的礼包码、绑定的归因参数才能对得上。如果只是把 App 拉起来却丢掉参数，运营那边看到的转化数据永远是断的。

换个场景也一样：老玩家在微信里收到一条邀请链接，点开后唤起游戏，客户端需要知道邀请人 ID、邀请码、来源群聊。又比如 Push 推送点击、客服工单跳转、深链进入某个活动页，本质上都是同一件事——通过一个 URL 把“外部世界”的信息带进“App 内部”，并且要在合适的时机把这份信息交到合适的业务模块手里。

所以做深链，至少要解决三个问题：入口怎么配，URL 怎么解析，参数在哪个时机、以什么形式投递给 C# 逻辑。任何一个环节没做好，线上就会出现“能打开但没效果”的假成功。

1.2 两条路线各有各的脾气

iOS 上实现 App 唤起的方案，主要是 URL Scheme 和 Universal Links 两条，两者不是替代关系，而是互补关系。

URL Scheme 是最老牌的做法，App 在 Info.plist 里注册一个类似mygame://的自定义协议，外部链接照着这个协议写，系统就会把链接交给你注册的 App。它的优点是接入简单、见效快，不依赖服务器配置，适用于 App 内部跳转和已知环境下的唤起。缺点是自定义协议可以被任何 App 声明，如果某个 scheme 被你注册了，别的 App 就不能用了，而且如果手机上没有安装对应 App，Safari 打开一个unknown://链接只会报错，体验很生硬。

Universal Links 是 iOS 9 之后引入的方案，它用普通的 HTTPS 链接来做唤起。链接本身是正常的云服务地址，比如https://mygame.example.com/event?id=123，系统在用户点击时去服务器上取一个apple-app-site-association（AASA）文件，确认这个域名确实授权给你的 App，然后直接在 Safari 顶部显示一个“在 App 中打开”的横幅，点一下就直接激活。未安装时，这个链接就是普通网页，可以放下载引导，体验完整得多。

两条路线的取舍，我放在下面的表里，方便你按项目情况选。

实战里我建议默认接入 Universal Links，同时保留一个独一无二、不太容易和别人冲突的 URL Scheme 作为兜底。原因后面在踩坑部分会细说，简单讲就是第三方 WebView 环境下 Universal Links 经常失效，只有自定义 scheme 还能在一定程度上做补偿。

2. iOS 侧入口配置：从 Xcode 到服务器文件

2.1 URL Scheme 配置实操

URL Scheme 配置本身不复杂，打开 Xcode 工程，选中 Target，切到 Info 标签页，在 URL Types 里添加一项就行。CFBundleURLName 填一个便于识别的名字，CFBundleURLSchemes 填你要用的协议名。

<key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLName</key> <string>com.yourcompany.yourgame.deep</string> <key>CFBundleURLSchemes</key> <array> <string>yourgameopen</string> </array> </dict> </array>

这里最关键的是 scheme 的唯一性。如果你的包名或品牌简写是可预测的，别人完全可以抢注一个一模一样的 scheme，到时候用户点击链接，iOS 无法保证唤起的一定是你的 App。我见过有人顺手写了test://或者game://这种通用词，上了线才发现 Android 端能唤起、iOS 端唤起时系统弹窗让用户选客户端，体验非常差。

建议用“品牌缩写 + 业务含义”的组合，比如游戏叫《山海经》，可以注册成shanhaijing_open://。越长越有识别度，越不容易冲突。另外，链接参数别用全角符号、中文裸字符串，URL 里建议先做一次 encode。

调试验证的时候，最简单的命令是直接在 iOS 模拟器或真机 Safari 地址栏输入链接。也可以用 Xcode 自带的模拟器命令唤起：

xcrun simctl openurl booted "yourgameopen://open?channel=ad&campaign=summer"

能看到 App 被拉起，就说明 scheme 注册成功了。这一步的成功标准不是“打开了”，而是打开之后你的回调方法有没有拿到完整 URL，特别是 query 部分有没有被截断。

2.2 Universal Links 配置实操

Universal Links 配置比 scheme 多好几个环节，但每一步都有标准做法，照着走就不会乱。

第一步，去 Apple Developer 后台，找到你的 App ID，在 Capabilities 里打开 Associated Domains。这一步不做，后面 Xcode 里配再多都没用。

第二步，回到 Xcode 工程，在 Target 的 Signing & Capabilities 里点击 “+ Capability”，添加 Associated Domains，然后在这个 capability 下面加一条域名记录，格式必须是：

applinks:mygame.example.com

注意这里不写 https 前缀，直接写 applinks: 加上你的业务域名。这个过程会同步生成一个 entitlements 文件，打包后系统读取这个权限声明来判断 App 有没有资格处理对应域名的链接。

第三步，在域名服务器上放一个apple-app-site-association文件，没有任何扩展名，内容是一段 JSON：

{ "applinks": { "apps": [], "details": [ { "appID": "TEAMID.com.yourcompany.yourgame", "paths": ["*"] } ] } }

这个文件有两个可以放置的位置，一个是域名根目录，一个是.well-known目录。为了保证 CDN 或 Web 服务器不会拦截，我建议两个位置都放一份一模一样的文件。path 字段决定哪些路径允许唤起，填*表示全部开放，线上正式环境建议收敛一下，只开放你需要的路径前缀，比如：

"paths": ["/open/*", "/events/*", "NOT /admin/*"]

否则任何指向这个域名的非法链接都可能唤起你的 App，参数校验的工作量会大很多。

AASA 文件里的appID是 Team ID 和 Bundle ID 的组合，中间用点连接。Team ID 在开发者账号后台的 Membership 页面能看到，Bundle ID 就是你 iOS 工程的 bundle identifier，两个都对上才生效。部署完之后，在浏览器直接访问https://mygame.example.com/apple-app-site-association，能看回完整的 JSON 内容就说明服务器这边没问题。

到这里，Universal Links 的系统链路就通了：用户点击 HTTPS 链接 → iOS 先从域名拉取 AASA 文件 → 匹配 appID 和 path → 找到设备上已安装的 App → 唤起并把 URL 传给 App 的 delegate 方法。

2.3 服务器端 AASA 文件有哪些坑

AASA 文件是 Universal Links 里最容易被忽略、也最容易出问题的环节，我专门拿出来讲。

第一个坑是缓存。很多游戏业务线用的是 CDN 域名，AASA 文件一旦被 CDN 缓存，更新配置后旧版本可能持续生效十几个小时，甚至更久。排查时你会发现手机端一直取到旧文件，清浏览器缓存也没用。解决方式是给 AASA 文件单独设置 CDN 缓存策略，max-age 设小一点，或者直接绕过缓存。

第二个坑是格式。AASA 文件虽然看起来是 JSON，但 Apple 的解析器对格式要求比较严格，文件内不能有注释、不能有重复键、不能有 BOM 头。不少人习惯用 Windows 记事本存 UTF-8 带 BOM 的格式，传上去之后 iOS 直接忽略文件，表现就是 Universal Links 完全没反应。

第三个坑是权限配置完整。有些团队 Web 服务器做了 URL 重写规则，把/.well-known/apple-app-site-association重写到了其他路径，或者对无扩展名文件返回了 404。这个文件必须能被公网直接访问，不能用登录鉴权包裹。

我习惯的验证命令：

curl -i https://mygame.example.com/apple-app-site-association

正常响应应该包含Content-Type: application/json或纯文本内容，HTTP 状态码是 200，响应体是你看到的 AASA JSON。如果有跳转、重写或缓存标记，第一步就要在服务端处理掉。

3. Unity 侧桥接与 C# 层参数投递

3.1 为什么建议原生插件做双保险

接到 Unity 工程之后，问题就变成：iOS 原生层拿到的 URL，怎么稳定地送到 C# 层。

很多人第一反应是用 Unity 官方提供的事件Application.deepLinkActivated。这个事件确实能覆盖大部分情况，官方文档里也写了 iOS、Android、Universal Windows Platform 等平台的支持。但在线上环境，我仍然建议在原生层补一手双保险，原因有三个。

一是时机问题。冷启动时 Unity Engine 还没完成初始化，系统通过continueUserActivity把 URL 传给 AppDelegate 时，Unity 侧的脚本对象可能根本还不存在，官方事件是否能可靠触发，受 Unity 版本和工程配置影响。有的项目改过启动流程、接了自己的 SDK 初始化逻辑，事件触发顺序就变了，靠官方事件兜底容易丢参数。

二是部分业务要求在打开的一瞬间就知道 URL，比如广告归因 SDK 需要在下发配置前拿到点击参数。这时候原生层先缓存一份 URL，再通过桥接层交给 C#，比等 Unity 自家事件更可控。

三是自定义逻辑的需要。有些团队要拦截不合规的来源、做本地签名校验，这些逻辑放在原生层更安全，不好逆向。

我采用的是 UnityAppController 子类方案，在 Xcode 生成的工程里写一个继承 UnityAppController 的类，重写两个方法：一个处理 URL Scheme，一个处理 Universal Links。

#import <UIKit/UIKit.h> #import "UnityAppController.h" @interface DeepLinkAppController : UnityAppController @end @implementation DeepLinkAppController - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options { if (url) { UnitySendMessage("DeepLinkHandler", "OnDeepLinkFromNative", url.absoluteString.UTF8String); return YES; } return [super application:app openURL:url options:options]; } - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler { if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) { NSURL *url = userActivity.webpageURL; if (url) { UnitySendMessage("DeepLinkHandler", "OnDeepLinkFromNative", url.absoluteString.UTF8String); } } return [super application:application continueUserActivity:userActivity restorationHandler:restorationHandler]; } @end

注意 UnitySendMessage 的第一个参数是场景里 GameObject 的名称，第二个参数是挂在它身上的 MonoBehaviour 的方法名。调用前要保证这个 GameObject 已经存在，冷启动时可以先在 C# 侧缓存一个待处理的静态队列，等 Awake 之后再取。另一个细节是，自建子类必须保证链接进主工程，不要被链接器优化掉。手动生成的 Xcode 工程里，可以在 main.mm 中把原来的 UnityAppController 换成你的子类名；用自动化打包脚本时，也要在脚本里做这一步替换。

Swift 项目同理，在 AppDelegate 里同样拿到 URL 后调用 UnitySendMessage，只是需要先 import UnityFramework，并把 UnitySendMessage 视作 C 接口调用来处理。

3.2 C# 层接收与参数解析

C# 这边需要一个专门挂在空的 GameObject 上的脚本，名字和原生层约定的一致。为了方便业务模块调用，我一般把它做成单例，所有外部 URL 统一走一个入口，Load 到场景里后 DontDestroyOnLoad。

using System; using System.Collections.Generic; using UnityEngine; public class DeepLinkHandler : MonoBehaviour { public static DeepLinkHandler Instance { get; private set; } private Queue<string> _pendingUrls = new Queue<string>(); private bool _ready; private void Awake() { if (Instance != null && Instance != this) { Destroy(gameObject); return; } Instance = this; DontDestroyOnLoad(gameObject); Application.deepLinkActivated += OnDeepLinkActivated; } public void MarkReady() { _ready = true; while (_pendingUrls.Count > 0) { Dispatch(_pendingUrls.Dequeue()); } } public void OnDeepLinkFromNative(string url) { FeedUrl(url); } private void OnDeepLinkActivated(string url) { FeedUrl(url); } private void FeedUrl(string url) { if (string.IsNullOrEmpty(url)) return; if (_ready) { Dispatch(url); } else { _pendingUrls.Enqueue(url); } } private void Dispatch(string url) { // 在这里解析、分发 Debug.Log($"[DeepLink] Got URL: {url}"); } }

这里的核心逻辑是把“已经准备好的时机”和“URL 到达的时机”解耦。冷启动时先入队，等游戏主流程初始化完成、登录回调拿到之后，再统一消费，这样就不会出现场景还在加载就跳到某个界面，结果界面依赖的数据还没准备好的问题。

参数解析同样要细致。URL 的形态可能是这样：

yourgameopen://open?channel=ad&campaign=summer&uid=1024 https://mygame.example.com/open?channel=ad&campaign=summer&uid=1024

解析 query 时不要按位置去取，用字典来转：

public static Dictionary<string, string> ParseQuery(string url) { var dict = new Dictionary<string, string>(); int idx = url.IndexOf('?'); if (idx < 0 || idx == url.Length - 1) return dict; string query = url.Substring(idx + 1); string[] pairs = query.Split('&'); foreach (var pair in pairs) { if (string.IsNullOrEmpty(pair)) continue; string[] kv = pair.Split('='); string key = Uri.UnescapeDataString(kv[0]); string val = kv.Length > 1 ? Uri.UnescapeDataString(kv[1].Replace('+', ' ')) : ""; dict[key] = val; } return dict; }

有个不起眼但线上一定会遇到的细节：URL 编码里+代表空格。直接用Uri.UnescapeDataString解出来的+不会被转成空格，导致参数“a+b”变“a+b”，对签名校验这种场景就是致命的。所以我上面把+手动 replace 成空格，再交给解码函数，这一点很多博客没提。

分发时建议做几层校验。第一层校验来源，Universal Links 链接里的域名必须是你自己的域名；URL Scheme 链接要在业务层约定一个版本号或者固定前缀。第二层校验时效，活动邀请链接最好带到期时间，不能一个链接在生产环境能用三年。第三层校验幂等，同一个 URL 重复唤起时不要重复触发“领奖”“弹活动页”这类副作用逻辑，用一个字典缓存最近处理过的 URL hash。

3.3 冷启动、热启动、后台恢复的分发时机

深链分发里最容易翻车的就是生命周期判断。我见过不少项目，明明 URL 拿到了，但表现是“这次打开了没反应，下次打开才生效”，问题基本都在冷启动顺序上。

冷启动时 App 进程从无到有，iOS 原生可能先是拿到 Universal Link，再创建 Unity 引擎，然后才加载第一个场景。此时如果原生直接 UnitySendMessage，发给谁？场景里的对象还没创建，消息会丢掉。所以要像前面代码那样，在 C# 层准备一个待处理队列。

热启动指 App 已经在运行，用户通过链接再次唤起。这种情况场景对象都在，消息可以直接分发，但也要注意当前有没有弹窗、是否处于登录流程。如果用户在支付页面被深链打断，分发一个跳转活动页的事件，就会把支付流程顶掉，引发支付状态和页面状态不一致。我的习惯是热启动时把事件丢给一个启动路由中心，由当前场景栈决定“立即执行”还是“等当前业务结束后再执行”。

后台恢复是最容易被忽略的。App 被用户滑到后台超过一段时间，系统可能已经回收部分资源，但进程还没死。这时 URL 到达，Unity 侧事件触发，场景里的管理器对象可能还活着，但网络状态已经不再可靠。不能默认“收到事件 = 可以立刻发请求”，要检查网络可达性、请求超时时间，最稳妥的做法是先回主线程、延迟一帧再分发。

我这边的参考实现，是在 DeepLinkHandler 上再加一层 Router，Router 统一监听启动流程状态：

private void Start() { // 最简单的方式：等首帧结束，再消费待处理深链 StartCoroutine(ConsumeAfterFirstFrame()); } private System.Collections.IEnumerator ConsumeAfterFirstFrame() { yield return null; MarkReady(); }

如果你的项目有登录态、配置表下发等更重的初始化，就把 MarkReady 挂到这些流程的完成回调里，而不是在 Start 直接调。这个接口设计比堆一堆 delay 要干净得多。

4. 调试与问题排查实录

4.1 我用这些命令和方法验证

调试深链跟调试普通业务代码不一样，很多问题光看 Xcode 控制台看不出来，得结合系统层日志、命令行工具、真机行为一起看。

最常用的一条命令是 macOS 终端的日志流过滤。把 iPhone 连上 Mac，打开 Xcode 的 Devices 窗口，或者直接用：

log stream --predicate 'eventMessage contains "apple-app-site-association"'

然后在 Safari 里点一下你的 Universal Link，再回来观察日志里有没有 AASA 拉取、匹配失败之类的系统提示。这个命令能直接看出 iOS 有没有成功访问你服务器上的 AASA 文件，以及它解析出来的 appID 是什么。

URL Scheme 可以用模拟器验证，模拟器里可以直接执行：

xcrun simctl openurl booted "yourgameopen://open?channel=test"

但 Universal Links 我强烈建议用真机验证，因为模拟器环境和 AASA 拉取策略跟真机有差异，模拟器上成功不代表真机就没问题。

另外，重签名的包和 App Store 包在很多行为上不一样。用个人开发者证书重签调试时，Universal Links 偶尔会出现不稳定的唤起结果，这不一定是代码问题，而是 TestFlight 包、开发包、生产包对 Associated Domains 的信任粒度不同。遇到这种情况，先换一台干净的、没有安装过其他版本 App 的设备再试一次。

4.2 高频问题速查表

我把这一年多排查总结的高频问题做成了速查表，遇到问题直接对着查。

4.3 我踩过的三个典型坑

第一个坑是 CDN 缓存导致的“版本分裂”。有一次我改了 AASA 文件里的 paths 规则，测试手机怎么刷新都是旧规则，过了几个小时才正常。后来 CDN 那边说是针对无扩展名文件做了默认缓存，max-age 设成了 6 小时。从那以后我养成了两个习惯：aasa 文件路径只走固定的两个位置；服务器返回头主动带上Cache-Control: no-cache，在 CDN 层面再做一次规则匹配。

第二个坑是微信等内置浏览器根本不执行 Universal Links 的完整链路，它只会把 URL 当作普通网页加载。业务方如果坚持要在微信里“点一下直接打开 App”，就得先做一个中间页，中间页用 JS 检测环境，再引导跳转。遇到这种情况我不会硬刚，而是让 H5 页面提供两个按钮，一个按钮试 Universal Links，另一个按钮展示“在 Safari 中打开”的操作指引，同时记录点击时的来源参数，等用户真正进游戏后再补发一次。

第三个坑是重签名的调试包掩盖了配置错误。有一次同事报 bug 说链接完全没反应，我看了半天代码没问题，最后发现他用的越狱测试机上装的是重签包，Associated Domains 权限根本没签进去，系统自然不认。这个环境问题会浪费大量排查时间，所以我现在调试前一定会先确认真机安装包的签名信息，别在错误的前提下找代码问题。

最后再分享一个我自己验证过的习惯：把深链统一收敛成一个启动事件总线，任何业务模块都不直接监听链接，而是监听“深链已解析”和“启动流程已就绪”两个事件。这样无论链路来自 URL Scheme、Universal Links 还是 Push 点击，最终走的都是同一套解析和分发路径，避免各端各写一套，也为后续接 Android App Links 留了一个干净的扩展点。