企业官网建设流程全解析

简介：这份资源面向需要在 Ionic 混合应用中嵌入 Unity 3D 内容的移动端开发者，重点解决 Android 与 iOS 双平台上 Unity 与 Ionic 之间的通信问题，并可选配合 Vuforia 插件实现 AR 场景。教程已在中等规模的 Unity 商业项目中验证，适合具备 Cordova、Objective-C++ 与 C# 基础的进阶开发者参考。压缩包共 21 个文件，约 424KB，包含 png 截图、mm 与 m 源文件、java 与 h 头文件、xml 配置、xcconfig 构建配置、json 与 js 脚本以及 cs 脚本等，覆盖 iOS 与 Android 两端桥接代码、插件声明与示例页面。目前已有 228 人学习下载。读者可从中获得完整的双端集成骨架、Unity 与 Ionic 互发消息的实现思路、Vuforia 接入的参考配置，以及按平台拆分的目录结构，便于快速对照搭建自己的混合 AR 应用。

1. UnityIonicIntegration 环境搭建：从 Unity 3D 到 Ionic 的消息通道

把 Unity 3D 场景塞进 Ionic 应用，还要让两边互相发消息，这事听起来像把两个不同星球的生物关进同一个笼子。我第一次接到这个需求时，以为装个 Cordova 插件就完事，结果 Android 和 iOS 各炸一次，光环境就折腾了两天。UnityIonicIntegration 这套方案解决的就是这个场景：Unity 负责 3D 渲染和 AR 逻辑，Ionic 负责业务 UI 和页面路由，两者通过 Cordova 插件桥接，在 Android 和 iOS 上互发消息。它适合正在做 AR 应用、3D 展示类 App 的开发者，尤其是已经用 Vuforia 做图像识别的团队。装不好会怎样？Unity 画面黑屏、消息发出去收不到、iOS 编译报 Objective-C++ 链接错误，每一个都能让你卡到怀疑人生。下面把我踩过的路按顺序铺开。

2. 环境准备：Unity、Ionic、Cordova 三件套的版本对齐

2.1 版本选择与兼容性对照

这套集成对版本敏感，不是随便装最新版就能跑。我一般会先把三个核心组件的版本锁死，再动手装。Unity 这边，建议用 LTS 版本，2021.3.x 或 2022.3.x 都行，关键是导出 Android 和 iOS 工程时不要选错模块。Ionic 这边，CLI 用 7.x，底层还是 Cordova 桥接，所以 Cordova CLI 要装 12.x 以上。Node.js 用 18 LTS，别用 20，某些 Cordova 插件在 Node 20 下会报ERR_OSSL_EVP_UNSUPPORTED。

Vuforia 插件如果要用，先在 Unity 里导入，版本选 10.x，它和 Unity 2021.3 LTS 配合最稳。装 Vuforia 之前先把 Unity 关掉，导入完再开，不然容易卡在包管理器。

2.2 安装 Ionic 与 Cordova 命令行工具

先装 Node.js 18 LTS，装完确认版本：

node -v # 应输出 v18.x.x npm -v # 应输出 9.x 或 10.x

然后全局装 Ionic CLI 和 Cordova CLI：

npm install -g @ionic/cli@7 cordova@12

装完验证：

ionic -v # 应输出 7.x.x cordova -v # 应输出 12.x.x

这里有个坑：如果你之前装过旧版 Ionic，先npm uninstall -g ionic再装@ionic/cli，因为旧包名是ionic，新包名是@ionic/cli，两个混在一起会命令冲突。我一般会顺手清一下 npm 缓存：npm cache clean --force，避免装到一半报校验失败。

2.3 创建 Ionic 项目并添加平台

新建一个 Ionic 项目，模板选 blank 就行：

ionic start UnityBridge blank --type=angular cd UnityBridge

然后添加 Android 和 iOS 平台：

ionic cordova platform add android ionic cordova platform add ios

注意，这里必须用ionic cordova而不是ionic capacitor，因为 UnityIonicIntegration 是基于 Cordova 插件桥接的，Capacitor 不兼容。添加平台时如果卡在Installing platform android，多半是网络问题，可以配一下 npm 镜像，或者手动下载 Cordova 平台包放到缓存目录。我一般会先cordova platform add android --verbose看详细日志，确认是下载慢还是 JDK 路径不对。

2.4 Unity 导出 Android 与 iOS 工程

Unity 这边，先建一个 3D 项目，把 Vuforia 导入，场景里放一个 ARCamera 和 ImageTarget，确认能在编辑器里跑通。然后导出：

• Android：File → Build Settings → Android → Switch Platform → Export Project（勾选 Export Project，不要选 Build and Run）
• iOS：File → Build Settings → iOS → Switch Platform → Build

导出 Android 工程时，Package Name 要和 Ionic 项目的包名一致，比如com.example.unitybridge。导出 iOS 工程时，Bundle Identifier 也要一致。这两个包名不一致，后面消息通道会断，因为插件是按包名找 Activity 和 ViewController 的。

导出完成后，Android 工程是一个 Gradle 项目目录，iOS 工程是一个 Xcode 项目目录。这两个目录后面要分别嵌入到 Ionic 的 Cordova 平台里。

3. 集成配置：把 Unity 工程嵌入 Ionic 并打通消息通道

3.1 Android 侧：嵌入 Unity 工程与配置 Gradle

Android 侧的集成，核心是把 Unity 导出的 Gradle 项目作为模块引入 Ionic 的 Cordova Android 工程。先把 Unity 导出的 Android 工程目录整个拷到 Ionic 项目的platforms/android下，改名为unitymodule。然后在platforms/android/settings.gradle里加一行：

include ':unitymodule' project(':unitymodule').projectDir = new File('unitymodule')

接着在platforms/android/app/build.gradle的 dependencies 里加：

implementation project(':unitymodule')

这里有个关键点：Unity 导出的build.gradle里 compileSdkVersion 和 targetSdkVersion 可能和 Ionic 工程不一致，我一般会把 Unity 模块的这两个值改成和 Ionic 工程一样，避免合并 manifest 时冲突。改完执行：

cd platforms/android ./gradlew clean ./gradlew assembleDebug

如果报Duplicate class或Manifest merger failed，多半是 AndroidX 和 support 库混用，在gradle.properties里加：

android.useAndroidX=true android.enableJetifier=true

然后重新 clean 再编译。这一步过了，Android 侧的基础集成就算通了。

3.2 iOS 侧：嵌入 Unity 工程与 Objective-C++ 桥接

iOS 侧比 Android 麻烦，因为 Unity 导出的是 Xcode 工程，要作为子工程嵌入 Cordova 的 iOS 工程。先把 Unity 导出的 iOS 目录拷到platforms/ios下，改名为UnityModule。然后用 Xcode 打开platforms/ios/UnityBridge.xcworkspace，把UnityModule/Unity-iPhone.xcodeproj拖进项目导航栏，作为子工程。

接着配置 Build Settings：

• 在 UnityBridge target 的 Build Phases → Link Binary With Libraries 里，把 UnityModule 的UnityFramework.framework加进去
• 在 Build Settings → Header Search Paths 里加$(SRCROOT)/UnityModule/Classes和$(SRCROOT)/UnityModule/Libraries
• 在 Build Settings → Other Linker Flags 里加-weak_framework UnityFramework

消息通道的桥接文件用 Objective-C++ 写，因为 Unity 的 iOS 接口是 C++ 的，Cordova 插件是 Objective-C 的，中间必须用.mm文件做桥。我一般会建一个UnityBridgePlugin.mm，里面同时 include Cordova 的CDVPlugin.h和 Unity 的UnityFramework/UnityFramework.h，然后实现sendMessageToUnity和onUnityMessage两个方法。编译时如果报Undefined symbol，检查UnityFramework.framework是否真的链接进去了，有时候拖进子工程后忘了在 Link Binary 里加。

3.3 消息通道：Cordova 插件注册与双向通信

消息通道的核心是一个 Cordova 插件，Android 侧用 Java 调 Unity 的UnityPlayer.UnitySendMessage，iOS 侧用 Objective-C++ 调UnityFramework的sendMessageToGOWithName。插件注册在config.xml里：

<plugin name="UnityBridge" spec="UnityBridge"> <param name="ANDROID_PACKAGE_NAME" value="com.example.unitybridge" /> <param name="IOS_BUNDLE_ID" value="com.example.unitybridge" /> </plugin>

Android 侧发消息给 Unity：

// UnityBridgePlugin.java UnityPlayer.UnitySendMessage("MessageReceiver", "OnMessageFromIonic", message);

iOS 侧发消息给 Unity：

// UnityBridgePlugin.mm [[UnityFramework getInstance] sendMessageToGOWithName:"MessageReceiver" functionName:"OnMessageFromIonic" message:[message UTF8String]];

Unity 侧接收消息的脚本挂在MessageReceiver这个 GameObject 上：

// MessageReceiver.cs public void OnMessageFromIonic(string message) { Debug.Log("收到 Ionic 消息: " + message); // 处理消息，然后回传 UnityFramework.Instance.SendMessageToIonic("Unity 已收到: " + message); }

回传时，Android 用UnityPlayer.currentActivity.runOnUiThread调 Cordova 的webView.sendJavascript，iOS 用UnityFramework的sendMessageToGOWithName回调到插件，再转发给 Cordova。这里最容易翻车的是线程问题：Unity 的渲染线程和 Cordova 的 UI 线程不是同一个，直接跨线程调 UI 会崩。我一般会在插件里加一个 Handler 或 dispatch_async 到主线程再发。

4. 避坑排查：Android 与 iOS 集成中最容易翻车的 5 个点

4.1 现象：Android 编译报 Duplicate class，原因是 AndroidX 冲突

现象：./gradlew assembleDebug时报Duplicate class android.support.v4.app.Fragment和androidx.fragment.app.Fragment同时存在。

原因：Unity 导出的 Android 工程默认用旧版 support 库，而 Ionic 的 Cordova 工程已经迁到 AndroidX，两者混用导致类重复。

解决：在platforms/android/gradle.properties里加android.useAndroidX=true和android.enableJetifier=true，然后./gradlew clean再编译。如果还报，检查 Unity 模块的build.gradle里有没有implementation 'com.android.support:appcompat-v7:xx'，有就删掉，换成 AndroidX 对应包。

4.2 现象：iOS 编译报 Undefined symbol，原因是 UnityFramework 没链接

现象：Xcode 编译时报Undefined symbol: _UnityFrameworkGetInstance或_sendMessageToGOWithName。

原因：UnityModule 作为子工程拖进来了，但 UnityFramework.framework 没有加到 Link Binary With Libraries 里，或者 Header Search Paths 没配。

解决：在 UnityBridge target 的 Build Phases → Link Binary With Libraries 里手动加UnityFramework.framework，路径指向UnityModule/UnityFramework.framework。然后在 Build Settings → Header Search Paths 里加$(SRCROOT)/UnityModule/Classes和$(SRCROOT)/UnityModule/Libraries。改完 Clean Build Folder 再编译。

4.3 现象：消息发出去收不到，原因是 GameObject 名字对不上

现象：Ionic 调sendMessageToUnity后，Unity 侧没有任何日志，消息像石沉大海。

原因：UnitySendMessage的第一个参数是 GameObject 名字，必须和 Unity 场景里挂脚本的 GameObject 名字完全一致，包括大小写。我见过有人场景里叫MessageReceiver，代码里写messageReceiver，结果死活收不到。

解决：在 Unity 场景里确认挂MessageReceiver.cs的 GameObject 名字，然后插件里UnitySendMessage的第一个参数严格一致。Android 和 iOS 两边都要检查，因为两个平台是分开写的。

4.4 现象：iOS 上 Unity 画面黑屏，原因是 Metal 与 OpenGL 冲突

现象：iOS 真机上 Ionic 页面正常，但 Unity 视图区域全黑，日志里没有明显报错。

原因：Unity 导出 iOS 时默认用 Metal 渲染，而 Cordova 的 WebView 可能占用 OpenGL 上下文，两者冲突导致 Unity 渲染失败。

解决：在 Unity 的 Player Settings → iOS → Graphics APIs 里，把 Metal 去掉，只留 OpenGL ES 3.0。或者反过来，在 Cordova 的config.xml里加<preference name="UseWebViewEngine" value="WKWebView" />，让 WebView 用 WKWebView 而不是 UIWebView，减少图形上下文冲突。我一般两个都改，稳一点。

4.5 现象：Android 上消息回传崩溃，原因是线程不对

现象：Unity 调SendMessageToIonic后，Android 应用直接闪退，日志里报CalledFromWrongThreadException。

原因：Unity 的SendMessageToIonic是在 Unity 渲染线程里调的，而 Cordova 的webView.sendJavascript必须在 UI 线程调，跨线程直接崩。

解决：在 Android 插件的SendMessageToIonic方法里，用activity.runOnUiThread包一层：

activity.runOnUiThread(new Runnable() { @Override public void run() { webView.sendJavascript("javascript:onUnityMessage('" + message + "')"); } });

iOS 侧同理，用dispatch_async(dispatch_get_main_queue(), ^{ ... })包一层。这个坑我踩过两次，第一次不知道原因，第二次看到CalledFromWrongThreadException才反应过来。

5. 验证跑通：从 Ionic 发消息到 Unity 再回传的完整链路检查

装完不算完，得验证消息通道真的通了。我一般会按「Ionic → Unity → Ionic」的顺序走一遍，每一步都打日志，确认链路没有断点。

先在 Ionic 页面里加一个按钮，点击时调插件发消息：

// home.page.ts declare var cordova: any; sendToUnity() { cordova.plugins.UnityBridge.sendMessageToUnity( "Hello from Ionic", () => console.log("发送成功"), (err: any) => console.error("发送失败", err) ); }

然后在 Unity 的MessageReceiver.cs里加日志：

public void OnMessageFromIonic(string message) { Debug.Log("Unity 收到: " + message); UnityFramework.Instance.SendMessageToIonic("Echo: " + message); }

最后在 Ionic 侧监听回传：

// home.page.ts ngAfterViewInit() { document.addEventListener("unityMessage", (event: any) => { console.log("Ionic 收到回传: ", event.detail); }); }

验证时按这个顺序检查：

Android 上用adb logcat | grep Unity看 Unity 日志，iOS 上用 Xcode 控制台看。如果某一步断了，就回到对应章节检查配置。我一般会在每个环节加console.log或Debug.Log，确保消息每经过一个节点都有记录，这样断在哪一目了然。

还有一个技巧：如果 Android 上 Unity 画面显示但消息不通，先检查UnityPlayer.UnitySendMessage的 GameObject 名字，再检查 Unity 场景是否真的加载了MessageReceiver脚本。iOS 上如果消息通了但画面黑，检查 Metal 和 OpenGL 的设置。这两个平台的问题经常是反着来的，Android 画面容易通但消息容易断，iOS 消息容易通但画面容易黑。

从那以后我每次集成 Unity 和 Ionic，都强制走一遍「发消息 → 收消息 → 回传 → 收回传」的完整链路，不看到四个日志全打出来不算完。希望帮到你。

本文还有配套的精品资源，点击获取