简介：这份资源面向需要在 Ionic 混合应用中嵌入 Unity 3D 内容的移动开发者，重点解决 Android 与 iOS 双端集成及两者间消息通信的问题，并已在带 Vuforia 插件的中等规模 Unity 商业项目中验证。包内共 21 个文件，约 424KB，包含 Objective-C++ 与 Java 原生桥接代码、C# 通信脚本、JavaScript 调用文件、plugin.xml 插件配置、xcconfig 与 jar 依赖等，覆盖从原生层到前端层的完整链路，另附多张双端运行截图辅助理解。已有 228 人学习下载。读者可据此掌握 Unity 与 Ionic 的工程对接方式、消息收发机制与 Vuforia 增强现实的接入思路，并参考现成的目录结构与插件配置快速搭建自己的集成环境，减少跨平台调试中的试错成本。
1. 从一次“Unity 画面嵌不进 Ionic 页面”的翻车说起
如果你正在做 AR 类 App，大概率会遇到这个场景：Unity 里跑着 Vuforia 的识别逻辑和 3D 模型，但登录、列表、支付、设置这些业务页面用 Ionic 写更顺手，于是想把两者塞进同一个 App。真正动手才发现，Unity 导出的是 Android/iOS 原生工程，Ionic 走的是 Cordova/Capacitor 的 WebView 容器，两边根本不在一个进程模型里，画面嵌不进去、消息也传不过去。这个项目要解决的就是这件事：把 Unity 3D 内容作为原生视图集成进 Ionic 应用，并在两者之间建立双向消息通道，Android 和 iOS 都覆盖，而且已经用 Vuforia 插件验证过 AR 场景。适合谁？适合手里有 Unity AR 工程、又不想放弃 Ionic 快速迭代业务页面的移动端开发者。
2. 架构拆解：Unity 视图怎么塞进 Ionic 的 WebView 容器
2.1 整体分层：三层结构各管什么
这个项目的架构可以理解成三层。最上层是 Ionic 的 Web 层，负责业务 UI 和路由；中间层是 Cordova 插件桥，负责把 Web 层的调用翻译成原生调用；最底层是 Unity 导出的原生模块，负责渲染 3D 和 AR 识别。三层之间不直接互相引用，全部通过插件暴露的接口通信。
为什么不让 Ionic 直接加载 Unity 的 WebGL 版本？因为 Vuforia 的 AR 能力依赖原生相机和传感器，WebGL 版本拿不到这些底层权限，识别精度和帧率都撑不住。所以必须走原生集成路线，Unity 导出 Android 的unityLibrary模块和 iOS 的UnityFramework，再由 Cordova 插件把它们挂到 Ionic 的原生容器上。
常见做法是：Android 侧用一个FrameLayout承载 Unity 的UnityPlayer视图，通过Activity或Fragment管理生命周期；iOS 侧用UnityFramework的appController拿到rootView，再把它 add 到当前UIViewController的视图层级上。Ionic 的 WebView 和 Unity 视图是兄弟关系，谁在上层由业务决定——比如 AR 扫描时 Unity 全屏，退出扫描时把 Unity 视图隐藏，露出 Ionic 页面。
2.2 消息通道：从 Web 到 Unity 再回来
消息通道是整个项目最核心的部分。Ionic 侧调用cordova.exec发消息，插件原生层收到后转发给 Unity，Unity 处理完再通过原生层回调回 Web。这条链路在 Android 和 iOS 上的实现方式不同，但对外暴露的 JS 接口是一致的。
先看 JS 侧的调用方式：
// 调用插件发送消息到 Unity cordova.exec( function success(result) { // Unity 处理后的回调结果 console.log('Unity 返回:', result); }, function error(err) { console.error('调用失败:', err); }, 'UnityIonicPlugin', // 插件名 'sendMessageToUnity', // action 名 [{ type: 'scan_start', payload: '{"mode":"marker"}' }] // 参数 );这段代码里，cordova.exec的五个参数分别是成功回调、失败回调、插件名、action 名、参数数组。插件名要和原生注册的名字一致，action 名决定原生层走哪个分支。参数用对象包一层，方便后续扩展字段。
Android 侧的原生实现大致是这样：
// Cordova 插件的 execute 方法 @Override public boolean execute(String action, JSONArray args, CallbackContext callbackContext) { if ("sendMessageToUnity".equals(action)) { String json = args.optJSONObject(0).optString("payload"); // 通过 UnityPlayer 的 sendMessage 转发 UnityPlayer.UnitySendMessage("MessageBridge", "OnMessageFromWeb", json); callbackContext.success("sent"); return true; } return false; }UnitySendMessage的三个参数是 Unity 场景里的 GameObject 名、方法名、字符串参数。注意它只能传字符串，复杂结构要自己序列化成 JSON。GameObject 名和方法名必须和 Unity 工程里挂的脚本完全一致，大小写敏感，这是最容易翻车的地方。
iOS 侧对应的是：
// UnityFramework 的消息发送 - (void)sendMessageToUnity:(CDVInvokedUrlCommand *)command { NSString *payload = [command.arguments objectAtIndex:0]; // 调用 UnityFramework 暴露的方法 [[UnityFrameworkInstance appController] sendMessageToGOWithName:"MessageBridge" functionName:"OnMessageFromWeb" message:[payload UTF8String]]; CDVPluginResult *result = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK]; [self.commandDelegate sendPluginResult:result callbackId:command.callbackId]; }iOS 侧用的是sendMessageToGOWithName，参数含义和 Android 的UnitySendMessage对应。区别在于 iOS 需要先拿到UnityFramework的实例，这个实例在 Unity 导出时由UnityFramework.h暴露，集成时要确保 framework 已经正确链接。
2.3 目录结构：拿到源码先看哪里
拿到这份资源后，建议按这个顺序看目录：
| 目录/文件 | 作用 |
|---|---|
src/ | Ionic 侧源码，含插件调用封装 |
src/pages/ | 业务页面，AR 入口通常在这里 |
www/ | 构建后的 Web 资源 |
android/ | Android 原生工程，含 Unity 集成代码 |
ios/ | iOS 原生工程，含 UnityFramework 链接配置 |
unity/ | Unity 工程侧脚本，含消息接收脚本 |
plugin.xml | Cordova 插件声明，定义插件名和 action |
先看plugin.xml，它定义了插件对外暴露的接口名和参数格式，是理解整个通信链路的入口。然后看src/里的调用封装，最后对照android/和ios/的原生实现，就能把消息通道的完整链路串起来。
3. 跑起来：从环境准备到双端验证的完整步骤
3.1 环境准备与依赖版本
这个项目对版本比较敏感，Unity 和 Cordova 的版本不匹配会导致导出工程结构对不上。建议的版本组合是：Unity 2020 LTS 以上、Cordova CLI 10 以上、Ionic 5 以上、Android Gradle Plugin 4.0 以上、Xcode 12 以上。Vuforia 插件版本要和 Unity 版本对应，否则 AR 相机初始化会失败。
环境变量方面，Android 需要配好ANDROID_HOME和JAVA_HOME，iOS 需要确保pod命令可用。Unity 导出时勾选Export Project，不要选Build and Run，因为我们需要拿到完整的 Gradle 工程和 Xcode 工程来做集成。
提示：Unity 导出 Android 工程时，
Player Settings里的Scripting Backend要选 IL2CPP，Target Architectures勾选 ARM64 和 ARMv7，否则在部分真机上会闪退。
3.2 Android 侧集成与运行
第一步，把 Unity 导出的unityLibrary模块复制到 Ionic 工程的android/目录下，然后在settings.gradle里注册：
// android/settings.gradle include ':app' include ':unityLibrary' project(':unityLibrary').projectDir = new File('unityLibrary')第二步，在app/build.gradle的 dependencies 里加入 Unity 模块：
dependencies { implementation project(':unityLibrary') implementation fileTree(dir: project(':unityLibrary').getProjectDir().toString() + ('/libs'), include: ['*.jar']) }第三步，在MainActivity里初始化 UnityPlayer 并挂载视图。常见做法是在onCreate里创建UnityPlayer实例，把它的View加到根布局上，初始设为隐藏，等 Web 层发来scan_start消息再显示。
// 初始化 UnityPlayer UnityPlayer unityPlayer = new UnityPlayer(this); FrameLayout container = findViewById(R.id.unity_container); container.addView(unityPlayer.getView()); unityPlayer.getView().setVisibility(View.GONE);第四步，跑ionic cordova run android，在真机上验证。模拟器跑不了 AR，必须用真机。如果 Unity 画面黑屏，先检查unityLibrary的AndroidManifest.xml是否和主工程合并成功，再看libs下的 so 文件有没有被打进 APK。
3.3 iOS 侧集成与运行
iOS 侧比 Android 麻烦一些，因为 UnityFramework 的链接和视图挂载都要手动处理。第一步，把 Unity 导出的UnityFramework.framework和UnityAppController.h拖进 Xcode 工程，在Build Phases的Link Binary With Libraries里加入 framework。
第二步，在AppDelegate里启动 UnityFramework：
// 启动 UnityFramework UnityFramework *ufw = [UnityFramework getInstance]; [ufw setDataBundleId:"com.unity3d.framework"]; [ufw runUIApplicationMainWithArgc:argc argv:argv]; self.unityFramework = ufw;第三步，在需要显示 AR 的页面里，把 Unity 的rootView加到当前视图：
UIView *unityView = [[[UnityFramework getInstance] appController] rootView]; unityView.frame = self.view.bounds; [self.view addSubview:unityView];第四步，跑ionic cordova run ios。如果编译报 framework 找不到，检查Framework Search Paths是否指向了 framework 所在目录。如果运行时崩溃在getInstance，通常是 framework 没有正确加载，确认Embed & Sign设置正确。
3.4 消息联调：先通一条再扩展
双端都跑起来后，先别急着做复杂业务，用一条最简单的消息验证通道。在 Ionic 页面里发一个ping，Unity 侧收到后回一个pong，Web 层打印出来。这条通了，再扩展其他消息类型。
// 验证消息通道 cordova.exec( (res) => console.log('通道正常:', res), (err) => console.error('通道异常:', err), 'UnityIonicPlugin', 'sendMessageToUnity', [{ type: 'ping', payload: '{}' }] );Unity 侧接收脚本挂在名为MessageBridge的 GameObject 上：
// Unity 侧消息接收 public class MessageBridge : MonoBehaviour { public void OnMessageFromWeb(string json) { var msg = JsonUtility.FromJson<MessageData>(json); if (msg.type == "ping") { // 回传 pong SendToWeb("pong", "{}"); } } void SendToWeb(string type, string payload) { // 通过原生接口回传 #if UNITY_ANDROID using (AndroidJavaClass jc = new AndroidJavaClass("com.unity3d.player.UnityPlayer")) { AndroidJavaObject activity = jc.GetStatic<AndroidJavaObject>("currentActivity"); activity.Call("onUnityMessage", type, payload); } #elif UNITY_IOS // iOS 侧通过 extern "C" 回调 #endif } }这段脚本里，OnMessageFromWeb是原生层调用的入口，方法名必须和原生侧传的字符串完全一致。SendToWeb是回传逻辑，Android 通过AndroidJavaClass反射调用 Activity 的方法，iOS 通过 C 函数回调。回传链路是消息通道里最容易断的一环，建议先单独测回传，再测双向。
4. 避坑排查：集成过程中最容易翻车的五个点
4.1 Unity 画面黑屏或白屏
现象：Ionic 页面正常，但 Unity 视图区域一片黑或一片白。原因通常是 UnityPlayer 没有正确初始化，或者视图被 WebView 遮挡。解决：先确认UnityPlayer实例创建成功，再检查视图层级——Unity 视图要 add 到 WebView 的父容器上，而不是 WebView 内部。如果是白屏，多半是 Unity 场景没有加载，检查unityLibrary的assets目录是否完整复制。
4.2 消息发出去没反应
现象：cordova.exec调用成功回调触发了，但 Unity 侧方法没执行。原因通常是 GameObject 名或方法名拼写不一致，或者 GameObject 在场景切换时被销毁了。解决：把MessageBridge挂在一个DontDestroyOnLoad的常驻对象上，方法名用nameof或常量管理，避免手写字符串。Android 侧可以用adb logcat过滤Unity标签看有没有报错。
4.3 iOS 编译报 framework 架构不匹配
现象：Xcode 编译时报building for iOS, but the linked framework was built for iOS Simulator。原因是 Unity 导出的 framework 只包含真机架构，模拟器跑不了。解决：AR 功能本来就要真机测，直接连真机调试。如果确实需要模拟器编译，在Build Settings的Excluded Architectures里排除模拟器架构。
4.4 Vuforia 相机初始化失败
现象：Unity 视图显示了，但相机画面出不来，日志报相机权限或初始化错误。原因通常是AndroidManifest.xml里没加相机权限，或者 iOS 的Info.plist里没加NSCameraUsageDescription。解决：Android 加<uses-permission android:name="android.permission.CAMERA"/>，iOS 加相机权限描述字符串。另外确认 Vuforia 的 license key 已经填在 Unity 工程里。
4.5 返回 Ionic 页面后 Unity 还在后台跑
现象：退出 AR 页面后，Unity 的渲染线程还在跑，耗电且发热。原因是 UnityPlayer 没有暂停。解决：在 Ionic 页面离开时发消息让 Unity 暂停，Android 调unityPlayer.pause()，iOS 调[ufw pause:YES]。恢复时对应调 resume。这个生命周期管理不做，用户手机会烫得能煎蛋。
5. 二次开发：把消息通道改造成自己的业务总线
跑通之后，这个项目最大的价值不是 AR 本身，而是那条已经验证过的消息通道。你可以把它改造成自己的业务总线，让 Ionic 和 Unity 之间的通信不再是一堆散落的cordova.exec调用。
我的做法是封装一个 JS 侧的UnityBridge类，统一管理消息的发送、回调注册和超时：
class UnityBridge { constructor() { this.callbacks = new Map(); this.seq = 0; } send(type, payload = {}, timeout = 5000) { return new Promise((resolve, reject) => { const id = ++this.seq; this.callbacks.set(id, { resolve, reject }); cordova.exec( (res) => { const cb = this.callbacks.get(id); if (cb) { cb.resolve(res); this.callbacks.delete(id); } }, (err) => { const cb = this.callbacks.get(id); if (cb) { cb.reject(err); this.callbacks.delete(id); } }, 'UnityIonicPlugin', 'sendMessageToUnity', [{ id, type, payload: JSON.stringify(payload) }] ); setTimeout(() => { if (this.callbacks.has(id)) { this.callbacks.get(id).reject(new Error('timeout')); this.callbacks.delete(id); } }, timeout); }); } }这个封装解决了三个问题：一是用 Promise 替代回调地狱，二是用自增 id 匹配请求和响应，三是加了超时兜底。Unity 侧回传时把 id 原样带回，JS 侧就能找到对应的 Promise。
Unity 侧对应改成一个消息分发器：
public class MessageDispatcher : MonoBehaviour { void OnMessageFromWeb(string json) { var msg = JsonUtility.FromJson<Envelope>(json); switch (msg.type) { case "scan_start": StartScan(msg.payload); break; case "scan_stop": StopScan(); break; default: Debug.LogWarning("未知消息类型: " + msg.type); break; } } }改造完之后，新增一个业务消息只需要在 switch 里加一个 case，JS 侧调bridge.send('new_type', {...})就行。验证方法是先跑通ping/pong，再逐个替换原有调用，每替换一个就在真机上回归一次。
从那以后我每次集成 Unity 和 Web 容器，都强制先跑通一条最小消息链路再动业务代码，这个习惯帮我省了至少三次通宵排查。希望帮到你。
本文还有配套的精品资源，点击获取
