简介面向需要将Unity项目嵌入Android原生工程的开发者这份rar压缩包提供了一套完整的集成配置方案已有超过300人学习。内容从Unity端的导出设置切入覆盖在Build Settings中切换Android平台、配置Minimum/Target API Level以及启用IL2CPP脚本后端再到利用“Create Android Project”生成独立的Android Library工程随后讲解如何将该工程导入Android Studio并整合UnityPlayerActivity完成AndroidManifest权限声明与应用层次结构挂载。针对双向交互资料梳理了通过Java/Kotlin桥接类与UnityPlayer.UnitySendMessage互相调用的实现路径并补充了内存占用、多线程利用、Logcat日志定位、Profiler性能瓶颈分析以及不同设备兼容性测试等优化与发布前准备要点。压缩包整体约323.39MB采用rar格式打包适合具备一定Android基础、希望为App增加3D游戏或交互模块的中高级开发者参考。1. 把 Unity 塞进已有 Android 工程为什么比你想的更麻烦很多 Android 工程师拿到“Unity嵌入到Android原工程.rar”时第一反应是解压、复制、加依赖撑死再看一眼 README。但真正动手做过的都清楚Unity 和 Android 各有一套独立构建链不是把若干文件夹拷进 Android Studio 就能跑起来。这个压缩包里通常同时躺着 Unity 工程源码、导出的 Gradle 工程或 AAR偶尔还带一个 launcher 壳工程你需要先分辨清楚产物的形态再决定怎么接入最后还要处理两套 Activity 生命周期和资源合并规则。这篇文章按一线集成流程来写先教你怎么从压缩包里认出该用的那份产物再给最小可运行步骤然后把原生与 Unity 互调的桥接拆开讲最后集中说五个高频踩坑点。适合两类人一类是 Android 原厂开发要把已有 App 里某个模块换成 Unity 渲染另一类是 Unity 开发者要反过来把 Unity 内容交付给原生团队。无论哪边核心目标都是同一个让 Unity 内容像一个“原生组件”一样活着而不是变成一颗独走的 APK。2. 从 .rar 里拿到什么Unity 导出 Android 工程的三种形态与选型拿到压缩包第一步不是解压就编译而是先看它的产物形态。Unity 对 Android 的导出方式直接决定了后续所有操作选错了等于白干一个下午。2.1 先分辨压缩包里的三种常见形态Unity 在 Build Settings 里针对 Android 平台有三种常见产物勾选 Export Project 会生成一份完整的 Gradle 工程不勾选时直接 Build 会生成 AAR在某些版本里是 Gradle 工程或 APK取决于导出界面选项再有一种就是生成独立 APK。企业交接这类“Unity嵌入到Android原工程.rar”时压缩包里最常见的是 Unity 工程源码加一个 androidBuild 导出目录偶尔还会附一份文档说明。我的做法是先解压到纯英文路径再快速扫一遍目录结构。Windows 上如果你用中文用户名或者把压缩包解压到“桌面/新建文件夹”Unity 导出的工程经常会在 manifest 合并或 NDK 编译时报一些莫名其妙的路径错误。先看目录find . -maxdepth 3 -type d | grep -E unityLibrary|launcher|Assets|ProjectSettings | head -30这条命令把压缩包解压后的前 3 层目录里最关键的几个目录找出来。出现Assets和ProjectSettings说明里面有 Unity 原始工程出现unityLibrary说明里面有已经导出好的 Unity 模块出现launcher说明导出工程里还带了官方壳 App。需要说明的是Assets目录不能直接被 Android Studio 识别它必须先在 Unity 里导出一次才能变成 Android 能编译的模块。再补一条命令确认是不是完整 Gradle 工程find . -maxdepth 2 -name settings.gradle -exec grep -l unityLibrary {} \;如果在settings.gradle里能看到unityLibrary说明这个包是 Unity 的 Export Project 产物也就是完整工程模式。反之如果只有.aar后缀文件那就是模块交付模式。这两种方式的后续接入路径完全不同别混着用。2.2 目录结构与产物构成典型的 Unity 导出 Android 工程目录长这样androidBuild/ settings.gradle build.gradle gradle.properties unityLibrary/ build.gradle src/main/ AndroidManifest.xml java/com/unity3d/player/UnityPlayer.java jniLibs/ arm64-v8a/... armeabi-v7a/... assets/ bin/Data/... launcher/ build.gradle src/main/AndroidManifest.xml这里最关键的是unityLibrary目录。它承载了 Unity 的运行时本体libunity.so、libil2cpp.so等 JNI 库assets/bin/Data里的场景数据与全局 metadata以及UnityPlayer.java这个桥接类。launcher是 Unity 官方生成的壳应用里面只有一个启动 Activity用来单独跑 Unity 内容嵌入原工程时通常不用它。如果压缩包里只有 APK那交付方其实没有做成“嵌入”只是把 Unity 内容打成独立应用让你跳转这不属于原工程内嵌后面会提到为什么我一般会让对方重新交付 AAR 或导出工程。如果压缩包里既有 Unity 工程又有导出工程优先信导出版本而不是拿着 Unity 工程在自己机器上重新导出除非你手头 Unity 版本和交付方完全一致。重新导出经常会因为编辑器大版本不同导致 shader 和 IL2CPP 设置漂移画面表现和包体都会变。2.3 AAR、Gradle 工程还是 APK先把选型定下来在动手之前先看清楚三种形态的边界别把 APK 当成嵌入方案产物形态是否适合嵌入原工程适合场景主要问题APK不适合独立应用之间的跳转无法共享资源与账号体系返回栈割裂AAR最适合Android 团队自己维护主工程Unity 只交付模块manifest 和生命周期要靠桥接处理Export Project中等需要改 unityLibrary 源码、深度定制启动流程Gradle 配置容易和原工程打架AAR 方式是我个人最常用的。Unity 那边只要保证导出的 AAR 能编译Android 这边把它当作一个普通 module 挂进来主工程的其他业务完全不受影响。另一个现实原因是版本管理Unity 内容迭代频繁时AAR 单独发版Android 团队不需要重新同步整个导出工程而 Export Project 一旦双方 Gradle 版本不一致每次 merge 都在冲突。Export Project 的优势是你可以直接改unityLibrary里的AndroidManifest.xml甚至替换UnityPlayerActivity。但这也意味着你要承担它带来的 Gradle 插件、JNI 库、资源目录等一整套配置的维护成本对只想嵌入一个渲染模块的团队来说并不划算。2.4 用三条命令确认版本与构建参数接手压缩包后我会先用三条命令把关键版本信息全部打出来记在一张纸条上之后再遇到编译报错能迅速定位是哪个环节不匹配# 1. 看 Unity 编辑器版本 grep -E m_EditorVersion ProjectSettings/ProjectVersion.txt # 2. 看导出工程的 Gradle 包装版本 cat gradle/wrapper/gradle-wrapper.properties | grep distributionUrl # 3. 看导出工程里 unityLibrary 的 minSdk / targetSdk grep -E minSdk|targetSdk|compileSdk unityLibrary/build.gradle第一条告诉你交付方用的 Unity 版本第二条告诉你导出的 Gradle 预期环境第三条是后续和主工程合并时最容易冲突的三个值。注意第三条在 Unity 新版本里可能是unityLibrary/src/main/AndroidManifest.xml里的uses-sdk要看实际情况。拿到这三项后再决定主工程能不能匹配不能匹配时需要升级主工程还是让 Unity 方重新导出这比直接编译遇到报错再回来查要省时间得多。3. 把 Unity 的 AAR 并入 Android Studio最小可运行步骤选型定了之后最让人头疼的一步就是把 Unity 模块挂进 Android 工程。这里不讲复杂定制先把最小可运行链路打通。3.1 环境准备和版本匹配Unity、Gradle、AGP 三角关系Unity 导出的工程和 Android 主工程之间的版本冲突几乎可以排在我遇到过的接入问题第一位。Unity 编辑器版本越新导出的unityLibrary对 Gradle 和 Android Gradle PluginAGP的要求就越高而很多存量 Android 工程还停在老 AGP 上两者硬凑会出现大量编译错误且报错信息往往不直接说“版本不匹配”而是报 SDK 版本、JDK 版本或者某个 API 找不到。先做一次三方对账对账项看哪里常见矛盾Gradle 版本gradle/wrapper/gradle-wrapper.properties主工程与 unityLibrary 要求不一致AGP 版本根build.gradle里的com.android.tools.build:gradle与 Gradle 版本不匹配JDK 版本Android Studio 设置 /java -versionUnity 老工程不认新 JDKminSdk / targetSdkunityLibrary 的build.gradle或 manifestAAR 要求比主工程高我的经验是不要试图把 Unity 导出工程里的 Gradle 版本强行降到和主工程一致。unityLibrary里的部分任务脚本是针对特定 Gradle 版本写的降低版本后会出现 “Could not find method” 之类的晦涩报错。正确做法是让主工程往 Unity 导出版本靠拢或者干脆走 AAR 交付让 Unity 侧自己保证 AAR 的兼容性。如果你是非要在 Export Project 模式下接入那就以unityLibrary/build.gradle为准把主工程的 Gradle 和 AGP 升到能匹配的最小版本。3.2 在 settings.gradle 里挂载 unityLibrary假设你已经从压缩包里拿到了unityLibrary目录把它放到主工程app/libs/unityLibrary下再打开根目录的settings.gradle添加两行include :unityLibrary project(:unityLibrary).projectDir new File(app/libs/unityLibrary)第一行include告诉 Gradle 这是一个参与构建的子模块第二行把模块路径指向实际目录。注意new File(...)里的路径是相对根settings.gradle所在目录的如果你的主工程根目录是MyApp那就是MyApp/app/libs/unityLibrary别多写一层。如果你用的是 Gradle Kotlin DSL也就是settings.gradle.kts语法换成include(:unityLibrary) project(:unityLibrary).projectDir File(app/libs/unityLibrary)这里最容易翻车的是符号大小写和括号Groovy 里字符串用单引号Kotlin DSL 里File要用大写开头。另外如果unityLibrary目录本身自带build.gradle千万不要顺手把它删了或改包名除非你充分理解改了之后 JNI 库com.unity3d.player.UnityPlayer的引用关系会被打断。3.3 在主模块添加依赖并调整构建参数挂载好子模块后在主模块app/build.gradle的dependencies块里加上一行dependencies { implementation project(:unityLibrary) }此刻你以为能编译了其实大概率还会遇到两个问题JNI 库过多、ABI 不匹配。Unity 默认会导出一堆 ABI包括 x86但真机基本只用arm64-v8a和armeabi-v7a。为了让包体不至于因为塞了 x86 无谓变大同时避免部分模拟器直接崩溃我会在主模块android块里加android { defaultConfig { ndk { abiFilters arm64-v8a, armeabi-v7a } } packagingOptions { jniLibs { useLegacyPackaging true } } }abiFilters的意义是告诉 Gradle 只要这两种 CPU 架构的 so 库。Unity 的libil2cpp.so非常吃体积保留两个 arm ABI 是包体优化里最立竿见影的一步。useLegacyPackaging是为了避免 Android 10 以下的设备在安装解压 so 时出问题新工程里这行加不加通常都没事但加上更稳。需要提醒的是如果你只在真机上跑且目标设备的 CPU 都是 64 位可以只留arm64-v8a包体能再小一截但如果你的应用要上电视盒子或低端平板那里很可能还是 32 位系统只留 arm64 会在启动时直接报 “dlopen failed” 找不到库。保留两个 ABI 是最不折腾的默认值。3.4 manifest 合并Activity、权限和 tools:overrideLibraryUnity 模块自带一个AndroidManifest.xml里面声明了它需要的权限、Activity 和uses-sdk。合并到主工程时最常撞上的是minSdk比主工程高。此时在应用级AndroidManifest.xml根部加上uses-sdk tools:overrideLibrarycom.unity3d.player/这一行的意思是Unity 模块要求的 minSdk 比主工程高时允许以主工程为准强制合并。注意它必须写在manifest根节点下而且要用到xmlns:tools命名空间否则合并器直接报错。同时因为 Android 12 开始强制要求组件显式声明android:exported而 Unity 老版本导出的模块里通常没这个字段所以还需要在应用 manifest 里补一段activity android:namecom.unity3d.player.UnityPlayerActivity android:configChangeskeyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize|smallestScreenSize android:exportedfalse /configChanges是让 Unity 自己处理屏幕方向和键盘变化而不是重启 Activityexportedfalse表示这个 Activity 不对外部应用开放只允许在应用内部启动。如果你希望在外部通过 deep link 之类方式拉起 Unity 页面再考虑改成true否则保持false更安全。manifest 冲突的报错信息通常会直接告诉你哪个属性冲突不用慌先看是哪个标签、哪两个文件再用tools:replace或tools:overrideLibrary定向处理。我第一次接入时不信邪想一次性把所有标签都补齐结果反而把 Unity 模块里的android:name写岔了导致运行时找不到主题。现在我的习惯是先跑一次不带任何覆盖的构建让编译器把确切冲突抛出来再逐条补。3.5 首次运行从 Activity 而不是从 launcher 启动接入完成后先用 Android Studio 直接运行然后从主工程任意一个原生页面跳过去startActivity(Intent(this, UnityPlayerActivity::class.java))这是最简单的验证方式。如果能看到 Unity 的启动画面和场景内容且 Logcat 里没有抛异常说明 AAR 接入成功。真机上验证时我习惯先把主工程的 Application 主题临时设为 Manifest 默认主题避免因为主题资源缺失导致 Unity 黑屏。如果启动后一直卡在某个位置先不要急着查 Unity 脚本先看adb logcat里有没有 Unity 的日志adb logcat -s Unity能看到 Unity 加载日志说明模块本身没问题问题大概率在生命周期桥接看不到日志则说明 libunity.so 没有成功加载优先检查 ABI 是否匹配、主工程是否把 Unity 的 so 给压缩或删掉了。4. Unity 生命周期与 Android 原生代码互调Activity 切换和消息桥打通编译只是第一步真正的难点在运行时的 Activity 切换和双向消息。Unity 不是一个普通 View它有一套自己的渲染循环和生命周期和 Android 的 Activity 生命周期必须对齐否则就会黑屏、崩溃、播放声音但画面卡住。4.1 UnityPlayerActivity 和原生 Activity 启动顺序Unity 官方提供的UnityPlayerActivity是一个已经实现好在onResume/onPause里去调用UnityPlayer.pause()/resume()的壳。直接用它可以最快跑通但它有两个问题一是它是独立页面Unity 内容被包在一个全屏 Activity 里和原生 Fragment 体系没法融合二是外部跳进去再退出时UnityPlayerActivity的onDestroy会连带销毁 Unity 运行时下次进入要重新加载白屏等待明显。如果你需要把 Unity 嵌入到某个原生页面内部常见做法是自己写一个 Activity 持有UnityPlayer视图而不是继承官方类public class UnityActivity extends Activity { protected UnityPlayer unityPlayer; Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); unityPlayer new UnityPlayer(this); setContentView(unityPlayer); } Override protected void onPause() { super.onPause(); unityPlayer.pause(); } Override protected void onResume() { super.onResume(); unityPlayer.resume(); } Override protected void onDestroy() { unityPlayer.destroy(); super.onDestroy(); } }这段代码的关键是onPause和onResume必须成对出现。UnityPlayer内部管理着一个 GL 渲染线程你在onPause里不暂停它锁屏或切后台时 Unity 侧会继续渲染表现为画面卡住但声音还在你在onResume里不恢复它回来就可能黑屏。很多第一次接入的人只写了onCreate和onDestroy结果 App 一切到后台再回来Unity 画面就永久停在最后一帧就是这个原因。UnityPlayer.destroy()必须放在super.onDestroy()之前还是之后我习惯先destroy()再super.onDestroy()。如果你把系统回调先执行掉UnityPlayer 内部可能已经访问不到有效的 Window 和 Context销毁时更容易崩。4.2 从 Android 发消息给 UnityUnityPlayer.UnitySendMessage 的边界从 Android 侧向 Unity 发消息最常用的是UnityPlayer.UnitySendMessage。它接受三个参数GameObject 名称、方法名、消息内容全部是字符串。调用示例UnityPlayer.UnitySendMessage( BridgeObject, OnNativeMessage, hello_from_android )Unity 侧对应的脚本必须挂在名为BridgeObject的 GameObject 上并且该方法必须是 public没有返回值public class BridgeObject : MonoBehaviour { public void OnNativeMessage(string message) { Debug.Log(native-unity: message); } }这里最容易踩的一个坑是如果BridgeObject在调用时没有激活或者没有挂这个方法Unity 端不会报任何错误消息会被静默丢弃。你查半天 Logcat 什么都看不到最后发现只是对象名少写了一个字母。我当时的经验是在方法第一行就打日志先确认消息有没有进到 Unity再谈后续业务逻辑。另一个边界是UnitySendMessage只支持字符串参数。如果你要传一个对象比如登录后的用户信息不要试图把 Object 直接塞进第二个参数字段那个字段会做默认的ToString()结果不是你想要的。常见做法是先把对象序列化成 JSON 字符串val json JSONObject().apply { put(token, token) put(uid, uid) }.toString() UnityPlayer.UnitySendMessage(BridgeObject, OnLogin, json)Unity 侧再用JsonUtility.FromJson反序列化。注意JsonUtility和LitJson的字段命名规则不同字符串里字段名要和 C# 类字段完全一致否则反序列化出来全是默认值。另外UnitySendMessage并不是绝对线程安全的。虽然实现里多数情况下会入队到 Unity 主线程但你在 Android 子线程频繁调用时偶尔会有竞态问题。我一般会先在 Android 侧runOnUiThread包一下再调避免在异步回调里直接执行。4.3 从 Unity 发消息给 AndroidAndroidJavaClass 和 AndroidJavaObject反向的消息通道也就是 Unity 侧通知 Android最直接的方案是用AndroidJavaClass调用原生静态方法using UnityEngine; public class NativeBridge : MonoBehaviour { public void SendToAndroid(string methodName, string param) { using (AndroidJavaClass jc new AndroidJavaClass(com.your.app.NativeBridgeHelper)) { jc.CallStatic(methodName, param); } } }com.your.app.NativeBridgeHelper是你在 Android 工程里写的一个普通 Java 类方法必须是public static。比如public class NativeBridgeHelper { public static void showToast(final String msg) { UnityPlayer.currentActivity.runOnUiThread(new Runnable() { Override public void run() { Toast.makeText(UnityPlayer.currentActivity, msg, Toast.LENGTH_SHORT).show(); } }); } }注意这里必须用UnityPlayer.currentActivity.runOnUiThread把操作切到 Android UI 线程。Unity 的 Update 虽然跑在主线程但那是指 Unity 引擎线程不是 Android 的 UI 线程。直接在这里 new 一个 Toast 或者在原生线程里操作 View轻则弹不出来重则直接抛 “Can’t create handler inside thread that has not called Looper.prepare()”。如果你的原生方法不是静态方法AndroidJavaClass就不适用了。需要先用AndroidJavaObject拿到 Activity 实例再调用实例方法using (AndroidJavaClass unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer)) { AndroidJavaObject activity unityPlayer.GetStaticAndroidJavaObject(currentActivity); activity.Call(someInstanceMethod, param); }这条链路的坑在于currentActivity可能在 Unity 启动初期还没被赋值首次调用发生在Awake里很容易拿到空引用。我一般把原生调用延后到Start或者点击事件里避免在Awake阶段去依赖 Android 的 Activity。4.4 三种数据通道字符串、JSON 和共享文件实际项目里不可能只传一个“hello”更多时候是传登录态、埋点数据甚至图片路径。我的经验是按数据大小和实时性分成三条通道短消息和命令用UnitySendMessage实时性最好但只能是字符串。结构化参数用 JSON 字符串Unity 侧用JsonUtility反序列化成强类型对象。数据量更大、超过几十 KB或者要传文件路径时走 Android 侧把内容写到getExternalFilesDirUnity 侧再定时读取或由 Android 发一条 Ready 消息通知 Unity 来读。共享文件通道最容易在 Android 11 上出问题。Android 10 开始对/storage/emulated/0/Android/data/目录的访问加了很多限制Android 11 下直接访问其他应用目录路径会抛Permission denied。但如果你读写的是自己应用getExternalFilesDir下的目录系统默认放行不需要额外申请权限。Unity 里不要手写死那个绝对路径正确做法还是走原生桥接把路径传进来String realPath UnityPlayer.currentActivity.getExternalFilesDir(null).getAbsolutePath();然后通过UnitySendMessage把这个路径发给 Unity。这样不管手机上有没有外置 SD 卡、厂商有没有魔改路径都不会踩到分区存储的规则。4.5 返回键和切后台处理不要轻易 finish()用一个独立 UnityPlayerActivity 嵌入时很多人以为返回键就是finish()直接关掉 Unity 页面回到原生。但 Unity 内容里如果有未保存状态或者正在播放场景动画直接关掉会导致后台还在运行的协程和资源一起被强杀下次进入重新加载又是一阵白屏。我常用的模式是返回键先发给 Unity让 Unity 自己决定是否允许退出override fun onBackPressed() { UnityPlayer.UnitySendMessage(GameManager, OnBackPressed, ) }Unity 侧在GameManager里处理完业务逻辑后再通过AndroidJavaClass调原生方法执行真正的finish()。这种方式把退出决策权交给 Unity 内容原生只负责执行。这时候你还要在 Unity 侧加一个防重复标记避免用户连按两次返回键导致 finish 被调两次UnityPlayer.destroy()被重复执行会直接崩。切后台同理。如果你的 Activity 不是全屏的唯一页面在onWindowFocusChanged里也要做一次同步override fun onWindowFocusChanged(hasFocus: Boolean) { super.onWindowFocusChanged(hasFocus) unityPlayer.pause() if (hasFocus) { unityPlayer.resume() } }这里有一个细节Unity 的pause()如果在锁屏时被调用两次不会真的暂停两次但 resume 次数少于 pause 会出现画面恢复了音频却还卡着的情况。所以不要在onPause和onWindowFocusChanged里重复调用同一方法逻辑最好是“状态判断后再调用”。5. 嵌入后必踩的 5 个坑资源、混淆、权限和返回键这一章把我实际接过的项目里最高频的 5 个问题整理成踩坑记录每条按现象、原因、解决三个步骤说清楚按顺序排查能省下大半时间。5.1 manifest 合并把 UnityPlayerActivity 的 exported 改没了现象Debug 包在 Android 12 以上设备正常Release 包安装后从原生页面跳 Unity 时直接闪退或报Permission Denial: starting Intent。原因Android 12 开始要求所有带有 intent-filter 的 Activity 必须显式声明android:exported。Unity 老版本导出的unityLibrary里没写这个字段主工程的 manifest 也没有合并后系统默认把它当成false导致从外部 Intent 启动时被拦截。实际上没有 intent-filter 的 Activity 不强制 exported但如果你在主工程里复写了该 Activity 或者用了隐式跳转就会触发这个问题。解决在应用级AndroidManifest.xml里显式补上activity android:namecom.unity3d.player.UnityPlayerActivity android:exportedfalse /如果你确实需要从系统外部唤起这个 Unity 页面再改成true。同时记得在根节点加上xmlns:toolshttp://schemas.android.com/tools用tools:replaceandroid:exported覆盖 Unity 模块里的默认值。改完做一次assembleRelease看 manifest merger 是否通过别只在 debug 包上验证。5.2 混淆把 UnitySendMessage 的目标脚本方法名改掉现象Debug 包一切正常打 Release 包后 Android 通过UnitySendMessage调不到 Unity 里的OnNativeMessageLogcat 也没有报错Unity 端像什么都没发生一样。原因ProGuard 或 R8 在混淆时把 MonoBehaviour 里供反射调用的OnNativeMessage方法名改掉了。UnitySendMessage底层是拿字符串去找脚本方法的方法名一被混淆自然找不到。解决在proguard-rules.pro里保留 Unity 桥接脚本的公有方法-keep public class * extends UnityEngine.MonoBehaviour { public *; } -keepclassmembers class ** { public void OnNativeMessage(java.lang.String); }第一行是把所有继承 MonoBehaviour 的脚本整体保下来避免类名和方法名被改第二行是专门针对你要接收消息的桥接方法。如果以后新增了别的OnXXX方法也记得加进来。注意Unity 导出时如果启用了 IL2CPP 和 Managed Stripping光靠 ProGuard 不一定够还要在 Unity 侧把桥接 GameObject 挂的脚本类加到link.xml里防止裁剪这是很多团队容易漏的点。5.3 只留 armeabi-v7a 在高通 64 位设备上 SIGILL现象接入后在某款高通或猎户座 64 位机型上启动崩溃崩溃栈里能看到libunity.so的SIGILL或SIGSEGV但换一台老设备又正常。原因Unity 的导出产物里包含多个 ABI 对应的 so 和 IL2CPP 的数据文件。如果你为了包体瘦身把abiFilters只配了armeabi-v7a在只支持 64 位或者对 32 位兼容不完整的系统上系统虽然能安装但运行时会尝试以 x86/arm64 的方式执行 32 位库触发非法指令。解决不要只保留armeabi-v7a。日常真机调试和发布至少保留这两个ndk { abiFilters arm64-v8a, armeabi-v7a }在包体优化时如果你确定所有目标设备都是 64 位 CPU可以只保留arm64-v8a这会省下不少体积但必须先做设备抽样测试而不是拍脑袋决定。还有一种情况是你把useLegacyPackaging设成了falseAndroid 会选择提取 so 而非直接读取压缩包某些 ROM 对提取路径处理有问题也会导致启动时找不到库。改成true通常能规避一大部分玄学。5.4 Android 11 分区存储下访问 /storage/emulated/0 失败现象Unity 里写死路径/storage/emulated/0/Android/data/com.your.app/files/xxx在 Android 9 上读写正常Android 11 上偶发FileNotFoundException或者读出来是空文件。原因从 Android 10 开始强制分区存储Android 11 进一步收紧了应用对外部共享目录的访问。通过绝对路径直接访问其他应用 data 目录会被拒绝即使路径指向的是自己包名下也可能因为你用了旧的WRITE_EXTERNAL_STORAGE权限模式而失效。解决放弃硬编码绝对路径。Unity 侧读取文件时不要直接拼/storage/emulated/0/...而是通过原生桥接拿到标准目录之后再拼接。最简单的做法是用 Unity 自带的Application.persistentDataPath在 Android 上它对应的就是应用专属目录系统默认放行。如果你需要把文件放到用户可见的公共目录比如下载目录那是另一套 MediaStore 逻辑不要走绝对路径。总之凡是遇到路径相关的奇怪读写失败先检查是不是踩了分区存储的边界。5.5 从后台回来 Unity 黑屏时间缩放与生命周期混在一起现象Unity 页面切后台再回来屏幕全黑但声音还在播放或者画面停在最后一帧整个场景的动画像被冻结了。原因这里有两个常见因素叠加。一是 UnityPlayer 的pause()/resume()没跟上 Activity 生命周期Surface 被系统回收后 Unity 没有重建渲染目标。二是有人在切后台时把Time.timeScale直接设成了 0导致 Unity 里的独立脚本还在跑但所有动画和物理都停了看起来像整个场景消失了一样。解决先查生命周期再查 timeScale。生命周期问题参考 4.1 里的自定义 Activity 写法确保onPause/onResume成对调用。timeScale 的问题则是在 Unity 侧统一封装一个切后台事件不要直接改 timeScale而是只暂停需要暂停的 MonoBehaviourvoid OnApplicationPause(bool paused) { if (paused) { // 不要直接 Time.timeScale 0f // 改为逐个暂停业务组件或使用自定义的暂停状态 } }OnApplicationPause是 Unity 提供的标准回调和 Android 的onPause时序不完全一致需要在原生侧收到 onPause 后主动调 Unity 的暂停逻辑而不是只靠 Unity 自己。黑屏问题排查顺序很简单先看有没有声音有声音说明 libunity 和 Audio 还在工作问题在 Surface 或渲染线程没声音说明整个 Unity 运行时都可能挂了去 Logcat 找 crash 栈。6. 最后再折腾验证、性能与升级路线接入能跑通之后不要急着庆祝还有三件事值得花时间做验证帧率、查冷启动时间、想清楚后续升级路线。这里给一个我常用的验证手段。Unity 侧写一个最简单的性能记录脚本using System.IO; using UnityEngine; public class FpsLogger : MonoBehaviour { void Update() { if (Time.frameCount % 60 0) { string text (1f / Time.deltaTime).ToString(0.0); File.WriteAllText(Application.persistentDataPath /fps.txt, text); } } }跑一段业务后用 adb 把这个文件拉出来adb pull /sdcard/Android/data/com.your.app/files/fps.txt ./fps.txt这个方式比直接在 PC 上连 profiler 方便适合现场侧真机验证。注意Application.persistentDataPath对应的就是getExternalFilesDir的路径不需要额外权限也不会被分区存储卡住。如果你发现帧率在原生页面跳转后骤降先检查是不是 Unity 的QualitySettings里的 vsync 和 Android 的Choreographer打架把 Unity 的垂直同步计数设为 “Don’t Sync” 再测一次往往能解开一个性能谜团。冷启动时间可以打点记录从原生点击按钮到UnityPlayer第一次渲染帧出现这段时间主要由 IL2CPP 初始化和场景加载构成。如果超过 2 秒优先做Player Settings里的Managed Stripping Level调整再考虑场景拆分成 AB。升级 Unity 版本时不要直接拿旧工程打开新编辑器先在分支上导出一版空场景验证 AAR 兼容性。Unity 新版本里有些渲染特性比如 GPU Skinning需要设备支持 Vulkan 或 OpenGL ES 3.1老机型上不提前验证会在嵌入后直接黑屏。我早期接手这类压缩包时最蠢的做法是把整个 rar 解压后全部塞进 Git结果.gradle、local.properties和一堆临时产物被提交进去团队每个人拉下来都在猜哪里是真正的构建入口。后来我只提交unityLibrary模块和一份构建说明其余全部让 Unity 侧重新导出反而省心得多。框架选型和交付边界比任何一行桥接代码都值得提前讲清楚希望帮到你。本文还有配套的精品资源点击获取
简介面向需要将Unity项目嵌入Android原生工程的开发者这份rar压缩包提供了一套完整的集成配置方案已有超过300人学习。内容从Unity端的导出设置切入覆盖在Build Settings中切换Android平台、配置Minimum/Target API Level以及启用IL2CPP脚本后端再到利用“Create Android Project”生成独立的Android Library工程随后讲解如何将该工程导入Android Studio并整合UnityPlayerActivity完成AndroidManifest权限声明与应用层次结构挂载。针对双向交互资料梳理了通过Java/Kotlin桥接类与UnityPlayer.UnitySendMessage互相调用的实现路径并补充了内存占用、多线程利用、Logcat日志定位、Profiler性能瓶颈分析以及不同设备兼容性测试等优化与发布前准备要点。压缩包整体约323.39MB采用rar格式打包适合具备一定Android基础、希望为App增加3D游戏或交互模块的中高级开发者参考。1. 把 Unity 塞进已有 Android 工程为什么比你想的更麻烦很多 Android 工程师拿到“Unity嵌入到Android原工程.rar”时第一反应是解压、复制、加依赖撑死再看一眼 README。但真正动手做过的都清楚Unity 和 Android 各有一套独立构建链不是把若干文件夹拷进 Android Studio 就能跑起来。这个压缩包里通常同时躺着 Unity 工程源码、导出的 Gradle 工程或 AAR偶尔还带一个 launcher 壳工程你需要先分辨清楚产物的形态再决定怎么接入最后还要处理两套 Activity 生命周期和资源合并规则。这篇文章按一线集成流程来写先教你怎么从压缩包里认出该用的那份产物再给最小可运行步骤然后把原生与 Unity 互调的桥接拆开讲最后集中说五个高频踩坑点。适合两类人一类是 Android 原厂开发要把已有 App 里某个模块换成 Unity 渲染另一类是 Unity 开发者要反过来把 Unity 内容交付给原生团队。无论哪边核心目标都是同一个让 Unity 内容像一个“原生组件”一样活着而不是变成一颗独走的 APK。2. 从 .rar 里拿到什么Unity 导出 Android 工程的三种形态与选型拿到压缩包第一步不是解压就编译而是先看它的产物形态。Unity 对 Android 的导出方式直接决定了后续所有操作选错了等于白干一个下午。2.1 先分辨压缩包里的三种常见形态Unity 在 Build Settings 里针对 Android 平台有三种常见产物勾选 Export Project 会生成一份完整的 Gradle 工程不勾选时直接 Build 会生成 AAR在某些版本里是 Gradle 工程或 APK取决于导出界面选项再有一种就是生成独立 APK。企业交接这类“Unity嵌入到Android原工程.rar”时压缩包里最常见的是 Unity 工程源码加一个 androidBuild 导出目录偶尔还会附一份文档说明。我的做法是先解压到纯英文路径再快速扫一遍目录结构。Windows 上如果你用中文用户名或者把压缩包解压到“桌面/新建文件夹”Unity 导出的工程经常会在 manifest 合并或 NDK 编译时报一些莫名其妙的路径错误。先看目录find . -maxdepth 3 -type d | grep -E unityLibrary|launcher|Assets|ProjectSettings | head -30这条命令把压缩包解压后的前 3 层目录里最关键的几个目录找出来。出现Assets和ProjectSettings说明里面有 Unity 原始工程出现unityLibrary说明里面有已经导出好的 Unity 模块出现launcher说明导出工程里还带了官方壳 App。需要说明的是Assets目录不能直接被 Android Studio 识别它必须先在 Unity 里导出一次才能变成 Android 能编译的模块。再补一条命令确认是不是完整 Gradle 工程find . -maxdepth 2 -name settings.gradle -exec grep -l unityLibrary {} \;如果在settings.gradle里能看到unityLibrary说明这个包是 Unity 的 Export Project 产物也就是完整工程模式。反之如果只有.aar后缀文件那就是模块交付模式。这两种方式的后续接入路径完全不同别混着用。2.2 目录结构与产物构成典型的 Unity 导出 Android 工程目录长这样androidBuild/ settings.gradle build.gradle gradle.properties unityLibrary/ build.gradle src/main/ AndroidManifest.xml java/com/unity3d/player/UnityPlayer.java jniLibs/ arm64-v8a/... armeabi-v7a/... assets/ bin/Data/... launcher/ build.gradle src/main/AndroidManifest.xml这里最关键的是unityLibrary目录。它承载了 Unity 的运行时本体libunity.so、libil2cpp.so等 JNI 库assets/bin/Data里的场景数据与全局 metadata以及UnityPlayer.java这个桥接类。launcher是 Unity 官方生成的壳应用里面只有一个启动 Activity用来单独跑 Unity 内容嵌入原工程时通常不用它。如果压缩包里只有 APK那交付方其实没有做成“嵌入”只是把 Unity 内容打成独立应用让你跳转这不属于原工程内嵌后面会提到为什么我一般会让对方重新交付 AAR 或导出工程。如果压缩包里既有 Unity 工程又有导出工程优先信导出版本而不是拿着 Unity 工程在自己机器上重新导出除非你手头 Unity 版本和交付方完全一致。重新导出经常会因为编辑器大版本不同导致 shader 和 IL2CPP 设置漂移画面表现和包体都会变。2.3 AAR、Gradle 工程还是 APK先把选型定下来在动手之前先看清楚三种形态的边界别把 APK 当成嵌入方案产物形态是否适合嵌入原工程适合场景主要问题APK不适合独立应用之间的跳转无法共享资源与账号体系返回栈割裂AAR最适合Android 团队自己维护主工程Unity 只交付模块manifest 和生命周期要靠桥接处理Export Project中等需要改 unityLibrary 源码、深度定制启动流程Gradle 配置容易和原工程打架AAR 方式是我个人最常用的。Unity 那边只要保证导出的 AAR 能编译Android 这边把它当作一个普通 module 挂进来主工程的其他业务完全不受影响。另一个现实原因是版本管理Unity 内容迭代频繁时AAR 单独发版Android 团队不需要重新同步整个导出工程而 Export Project 一旦双方 Gradle 版本不一致每次 merge 都在冲突。Export Project 的优势是你可以直接改unityLibrary里的AndroidManifest.xml甚至替换UnityPlayerActivity。但这也意味着你要承担它带来的 Gradle 插件、JNI 库、资源目录等一整套配置的维护成本对只想嵌入一个渲染模块的团队来说并不划算。2.4 用三条命令确认版本与构建参数接手压缩包后我会先用三条命令把关键版本信息全部打出来记在一张纸条上之后再遇到编译报错能迅速定位是哪个环节不匹配# 1. 看 Unity 编辑器版本 grep -E m_EditorVersion ProjectSettings/ProjectVersion.txt # 2. 看导出工程的 Gradle 包装版本 cat gradle/wrapper/gradle-wrapper.properties | grep distributionUrl # 3. 看导出工程里 unityLibrary 的 minSdk / targetSdk grep -E minSdk|targetSdk|compileSdk unityLibrary/build.gradle第一条告诉你交付方用的 Unity 版本第二条告诉你导出的 Gradle 预期环境第三条是后续和主工程合并时最容易冲突的三个值。注意第三条在 Unity 新版本里可能是unityLibrary/src/main/AndroidManifest.xml里的uses-sdk要看实际情况。拿到这三项后再决定主工程能不能匹配不能匹配时需要升级主工程还是让 Unity 方重新导出这比直接编译遇到报错再回来查要省时间得多。3. 把 Unity 的 AAR 并入 Android Studio最小可运行步骤选型定了之后最让人头疼的一步就是把 Unity 模块挂进 Android 工程。这里不讲复杂定制先把最小可运行链路打通。3.1 环境准备和版本匹配Unity、Gradle、AGP 三角关系Unity 导出的工程和 Android 主工程之间的版本冲突几乎可以排在我遇到过的接入问题第一位。Unity 编辑器版本越新导出的unityLibrary对 Gradle 和 Android Gradle PluginAGP的要求就越高而很多存量 Android 工程还停在老 AGP 上两者硬凑会出现大量编译错误且报错信息往往不直接说“版本不匹配”而是报 SDK 版本、JDK 版本或者某个 API 找不到。先做一次三方对账对账项看哪里常见矛盾Gradle 版本gradle/wrapper/gradle-wrapper.properties主工程与 unityLibrary 要求不一致AGP 版本根build.gradle里的com.android.tools.build:gradle与 Gradle 版本不匹配JDK 版本Android Studio 设置 /java -versionUnity 老工程不认新 JDKminSdk / targetSdkunityLibrary 的build.gradle或 manifestAAR 要求比主工程高我的经验是不要试图把 Unity 导出工程里的 Gradle 版本强行降到和主工程一致。unityLibrary里的部分任务脚本是针对特定 Gradle 版本写的降低版本后会出现 “Could not find method” 之类的晦涩报错。正确做法是让主工程往 Unity 导出版本靠拢或者干脆走 AAR 交付让 Unity 侧自己保证 AAR 的兼容性。如果你是非要在 Export Project 模式下接入那就以unityLibrary/build.gradle为准把主工程的 Gradle 和 AGP 升到能匹配的最小版本。3.2 在 settings.gradle 里挂载 unityLibrary假设你已经从压缩包里拿到了unityLibrary目录把它放到主工程app/libs/unityLibrary下再打开根目录的settings.gradle添加两行include :unityLibrary project(:unityLibrary).projectDir new File(app/libs/unityLibrary)第一行include告诉 Gradle 这是一个参与构建的子模块第二行把模块路径指向实际目录。注意new File(...)里的路径是相对根settings.gradle所在目录的如果你的主工程根目录是MyApp那就是MyApp/app/libs/unityLibrary别多写一层。如果你用的是 Gradle Kotlin DSL也就是settings.gradle.kts语法换成include(:unityLibrary) project(:unityLibrary).projectDir File(app/libs/unityLibrary)这里最容易翻车的是符号大小写和括号Groovy 里字符串用单引号Kotlin DSL 里File要用大写开头。另外如果unityLibrary目录本身自带build.gradle千万不要顺手把它删了或改包名除非你充分理解改了之后 JNI 库com.unity3d.player.UnityPlayer的引用关系会被打断。3.3 在主模块添加依赖并调整构建参数挂载好子模块后在主模块app/build.gradle的dependencies块里加上一行dependencies { implementation project(:unityLibrary) }此刻你以为能编译了其实大概率还会遇到两个问题JNI 库过多、ABI 不匹配。Unity 默认会导出一堆 ABI包括 x86但真机基本只用arm64-v8a和armeabi-v7a。为了让包体不至于因为塞了 x86 无谓变大同时避免部分模拟器直接崩溃我会在主模块android块里加android { defaultConfig { ndk { abiFilters arm64-v8a, armeabi-v7a } } packagingOptions { jniLibs { useLegacyPackaging true } } }abiFilters的意义是告诉 Gradle 只要这两种 CPU 架构的 so 库。Unity 的libil2cpp.so非常吃体积保留两个 arm ABI 是包体优化里最立竿见影的一步。useLegacyPackaging是为了避免 Android 10 以下的设备在安装解压 so 时出问题新工程里这行加不加通常都没事但加上更稳。需要提醒的是如果你只在真机上跑且目标设备的 CPU 都是 64 位可以只留arm64-v8a包体能再小一截但如果你的应用要上电视盒子或低端平板那里很可能还是 32 位系统只留 arm64 会在启动时直接报 “dlopen failed” 找不到库。保留两个 ABI 是最不折腾的默认值。3.4 manifest 合并Activity、权限和 tools:overrideLibraryUnity 模块自带一个AndroidManifest.xml里面声明了它需要的权限、Activity 和uses-sdk。合并到主工程时最常撞上的是minSdk比主工程高。此时在应用级AndroidManifest.xml根部加上uses-sdk tools:overrideLibrarycom.unity3d.player/这一行的意思是Unity 模块要求的 minSdk 比主工程高时允许以主工程为准强制合并。注意它必须写在manifest根节点下而且要用到xmlns:tools命名空间否则合并器直接报错。同时因为 Android 12 开始强制要求组件显式声明android:exported而 Unity 老版本导出的模块里通常没这个字段所以还需要在应用 manifest 里补一段activity android:namecom.unity3d.player.UnityPlayerActivity android:configChangeskeyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize|smallestScreenSize android:exportedfalse /configChanges是让 Unity 自己处理屏幕方向和键盘变化而不是重启 Activityexportedfalse表示这个 Activity 不对外部应用开放只允许在应用内部启动。如果你希望在外部通过 deep link 之类方式拉起 Unity 页面再考虑改成true否则保持false更安全。manifest 冲突的报错信息通常会直接告诉你哪个属性冲突不用慌先看是哪个标签、哪两个文件再用tools:replace或tools:overrideLibrary定向处理。我第一次接入时不信邪想一次性把所有标签都补齐结果反而把 Unity 模块里的android:name写岔了导致运行时找不到主题。现在我的习惯是先跑一次不带任何覆盖的构建让编译器把确切冲突抛出来再逐条补。3.5 首次运行从 Activity 而不是从 launcher 启动接入完成后先用 Android Studio 直接运行然后从主工程任意一个原生页面跳过去startActivity(Intent(this, UnityPlayerActivity::class.java))这是最简单的验证方式。如果能看到 Unity 的启动画面和场景内容且 Logcat 里没有抛异常说明 AAR 接入成功。真机上验证时我习惯先把主工程的 Application 主题临时设为 Manifest 默认主题避免因为主题资源缺失导致 Unity 黑屏。如果启动后一直卡在某个位置先不要急着查 Unity 脚本先看adb logcat里有没有 Unity 的日志adb logcat -s Unity能看到 Unity 加载日志说明模块本身没问题问题大概率在生命周期桥接看不到日志则说明 libunity.so 没有成功加载优先检查 ABI 是否匹配、主工程是否把 Unity 的 so 给压缩或删掉了。4. Unity 生命周期与 Android 原生代码互调Activity 切换和消息桥打通编译只是第一步真正的难点在运行时的 Activity 切换和双向消息。Unity 不是一个普通 View它有一套自己的渲染循环和生命周期和 Android 的 Activity 生命周期必须对齐否则就会黑屏、崩溃、播放声音但画面卡住。4.1 UnityPlayerActivity 和原生 Activity 启动顺序Unity 官方提供的UnityPlayerActivity是一个已经实现好在onResume/onPause里去调用UnityPlayer.pause()/resume()的壳。直接用它可以最快跑通但它有两个问题一是它是独立页面Unity 内容被包在一个全屏 Activity 里和原生 Fragment 体系没法融合二是外部跳进去再退出时UnityPlayerActivity的onDestroy会连带销毁 Unity 运行时下次进入要重新加载白屏等待明显。如果你需要把 Unity 嵌入到某个原生页面内部常见做法是自己写一个 Activity 持有UnityPlayer视图而不是继承官方类public class UnityActivity extends Activity { protected UnityPlayer unityPlayer; Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); unityPlayer new UnityPlayer(this); setContentView(unityPlayer); } Override protected void onPause() { super.onPause(); unityPlayer.pause(); } Override protected void onResume() { super.onResume(); unityPlayer.resume(); } Override protected void onDestroy() { unityPlayer.destroy(); super.onDestroy(); } }这段代码的关键是onPause和onResume必须成对出现。UnityPlayer内部管理着一个 GL 渲染线程你在onPause里不暂停它锁屏或切后台时 Unity 侧会继续渲染表现为画面卡住但声音还在你在onResume里不恢复它回来就可能黑屏。很多第一次接入的人只写了onCreate和onDestroy结果 App 一切到后台再回来Unity 画面就永久停在最后一帧就是这个原因。UnityPlayer.destroy()必须放在super.onDestroy()之前还是之后我习惯先destroy()再super.onDestroy()。如果你把系统回调先执行掉UnityPlayer 内部可能已经访问不到有效的 Window 和 Context销毁时更容易崩。4.2 从 Android 发消息给 UnityUnityPlayer.UnitySendMessage 的边界从 Android 侧向 Unity 发消息最常用的是UnityPlayer.UnitySendMessage。它接受三个参数GameObject 名称、方法名、消息内容全部是字符串。调用示例UnityPlayer.UnitySendMessage( BridgeObject, OnNativeMessage, hello_from_android )Unity 侧对应的脚本必须挂在名为BridgeObject的 GameObject 上并且该方法必须是 public没有返回值public class BridgeObject : MonoBehaviour { public void OnNativeMessage(string message) { Debug.Log(native-unity: message); } }这里最容易踩的一个坑是如果BridgeObject在调用时没有激活或者没有挂这个方法Unity 端不会报任何错误消息会被静默丢弃。你查半天 Logcat 什么都看不到最后发现只是对象名少写了一个字母。我当时的经验是在方法第一行就打日志先确认消息有没有进到 Unity再谈后续业务逻辑。另一个边界是UnitySendMessage只支持字符串参数。如果你要传一个对象比如登录后的用户信息不要试图把 Object 直接塞进第二个参数字段那个字段会做默认的ToString()结果不是你想要的。常见做法是先把对象序列化成 JSON 字符串val json JSONObject().apply { put(token, token) put(uid, uid) }.toString() UnityPlayer.UnitySendMessage(BridgeObject, OnLogin, json)Unity 侧再用JsonUtility.FromJson反序列化。注意JsonUtility和LitJson的字段命名规则不同字符串里字段名要和 C# 类字段完全一致否则反序列化出来全是默认值。另外UnitySendMessage并不是绝对线程安全的。虽然实现里多数情况下会入队到 Unity 主线程但你在 Android 子线程频繁调用时偶尔会有竞态问题。我一般会先在 Android 侧runOnUiThread包一下再调避免在异步回调里直接执行。4.3 从 Unity 发消息给 AndroidAndroidJavaClass 和 AndroidJavaObject反向的消息通道也就是 Unity 侧通知 Android最直接的方案是用AndroidJavaClass调用原生静态方法using UnityEngine; public class NativeBridge : MonoBehaviour { public void SendToAndroid(string methodName, string param) { using (AndroidJavaClass jc new AndroidJavaClass(com.your.app.NativeBridgeHelper)) { jc.CallStatic(methodName, param); } } }com.your.app.NativeBridgeHelper是你在 Android 工程里写的一个普通 Java 类方法必须是public static。比如public class NativeBridgeHelper { public static void showToast(final String msg) { UnityPlayer.currentActivity.runOnUiThread(new Runnable() { Override public void run() { Toast.makeText(UnityPlayer.currentActivity, msg, Toast.LENGTH_SHORT).show(); } }); } }注意这里必须用UnityPlayer.currentActivity.runOnUiThread把操作切到 Android UI 线程。Unity 的 Update 虽然跑在主线程但那是指 Unity 引擎线程不是 Android 的 UI 线程。直接在这里 new 一个 Toast 或者在原生线程里操作 View轻则弹不出来重则直接抛 “Can’t create handler inside thread that has not called Looper.prepare()”。如果你的原生方法不是静态方法AndroidJavaClass就不适用了。需要先用AndroidJavaObject拿到 Activity 实例再调用实例方法using (AndroidJavaClass unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer)) { AndroidJavaObject activity unityPlayer.GetStaticAndroidJavaObject(currentActivity); activity.Call(someInstanceMethod, param); }这条链路的坑在于currentActivity可能在 Unity 启动初期还没被赋值首次调用发生在Awake里很容易拿到空引用。我一般把原生调用延后到Start或者点击事件里避免在Awake阶段去依赖 Android 的 Activity。4.4 三种数据通道字符串、JSON 和共享文件实际项目里不可能只传一个“hello”更多时候是传登录态、埋点数据甚至图片路径。我的经验是按数据大小和实时性分成三条通道短消息和命令用UnitySendMessage实时性最好但只能是字符串。结构化参数用 JSON 字符串Unity 侧用JsonUtility反序列化成强类型对象。数据量更大、超过几十 KB或者要传文件路径时走 Android 侧把内容写到getExternalFilesDirUnity 侧再定时读取或由 Android 发一条 Ready 消息通知 Unity 来读。共享文件通道最容易在 Android 11 上出问题。Android 10 开始对/storage/emulated/0/Android/data/目录的访问加了很多限制Android 11 下直接访问其他应用目录路径会抛Permission denied。但如果你读写的是自己应用getExternalFilesDir下的目录系统默认放行不需要额外申请权限。Unity 里不要手写死那个绝对路径正确做法还是走原生桥接把路径传进来String realPath UnityPlayer.currentActivity.getExternalFilesDir(null).getAbsolutePath();然后通过UnitySendMessage把这个路径发给 Unity。这样不管手机上有没有外置 SD 卡、厂商有没有魔改路径都不会踩到分区存储的规则。4.5 返回键和切后台处理不要轻易 finish()用一个独立 UnityPlayerActivity 嵌入时很多人以为返回键就是finish()直接关掉 Unity 页面回到原生。但 Unity 内容里如果有未保存状态或者正在播放场景动画直接关掉会导致后台还在运行的协程和资源一起被强杀下次进入重新加载又是一阵白屏。我常用的模式是返回键先发给 Unity让 Unity 自己决定是否允许退出override fun onBackPressed() { UnityPlayer.UnitySendMessage(GameManager, OnBackPressed, ) }Unity 侧在GameManager里处理完业务逻辑后再通过AndroidJavaClass调原生方法执行真正的finish()。这种方式把退出决策权交给 Unity 内容原生只负责执行。这时候你还要在 Unity 侧加一个防重复标记避免用户连按两次返回键导致 finish 被调两次UnityPlayer.destroy()被重复执行会直接崩。切后台同理。如果你的 Activity 不是全屏的唯一页面在onWindowFocusChanged里也要做一次同步override fun onWindowFocusChanged(hasFocus: Boolean) { super.onWindowFocusChanged(hasFocus) unityPlayer.pause() if (hasFocus) { unityPlayer.resume() } }这里有一个细节Unity 的pause()如果在锁屏时被调用两次不会真的暂停两次但 resume 次数少于 pause 会出现画面恢复了音频却还卡着的情况。所以不要在onPause和onWindowFocusChanged里重复调用同一方法逻辑最好是“状态判断后再调用”。5. 嵌入后必踩的 5 个坑资源、混淆、权限和返回键这一章把我实际接过的项目里最高频的 5 个问题整理成踩坑记录每条按现象、原因、解决三个步骤说清楚按顺序排查能省下大半时间。5.1 manifest 合并把 UnityPlayerActivity 的 exported 改没了现象Debug 包在 Android 12 以上设备正常Release 包安装后从原生页面跳 Unity 时直接闪退或报Permission Denial: starting Intent。原因Android 12 开始要求所有带有 intent-filter 的 Activity 必须显式声明android:exported。Unity 老版本导出的unityLibrary里没写这个字段主工程的 manifest 也没有合并后系统默认把它当成false导致从外部 Intent 启动时被拦截。实际上没有 intent-filter 的 Activity 不强制 exported但如果你在主工程里复写了该 Activity 或者用了隐式跳转就会触发这个问题。解决在应用级AndroidManifest.xml里显式补上activity android:namecom.unity3d.player.UnityPlayerActivity android:exportedfalse /如果你确实需要从系统外部唤起这个 Unity 页面再改成true。同时记得在根节点加上xmlns:toolshttp://schemas.android.com/tools用tools:replaceandroid:exported覆盖 Unity 模块里的默认值。改完做一次assembleRelease看 manifest merger 是否通过别只在 debug 包上验证。5.2 混淆把 UnitySendMessage 的目标脚本方法名改掉现象Debug 包一切正常打 Release 包后 Android 通过UnitySendMessage调不到 Unity 里的OnNativeMessageLogcat 也没有报错Unity 端像什么都没发生一样。原因ProGuard 或 R8 在混淆时把 MonoBehaviour 里供反射调用的OnNativeMessage方法名改掉了。UnitySendMessage底层是拿字符串去找脚本方法的方法名一被混淆自然找不到。解决在proguard-rules.pro里保留 Unity 桥接脚本的公有方法-keep public class * extends UnityEngine.MonoBehaviour { public *; } -keepclassmembers class ** { public void OnNativeMessage(java.lang.String); }第一行是把所有继承 MonoBehaviour 的脚本整体保下来避免类名和方法名被改第二行是专门针对你要接收消息的桥接方法。如果以后新增了别的OnXXX方法也记得加进来。注意Unity 导出时如果启用了 IL2CPP 和 Managed Stripping光靠 ProGuard 不一定够还要在 Unity 侧把桥接 GameObject 挂的脚本类加到link.xml里防止裁剪这是很多团队容易漏的点。5.3 只留 armeabi-v7a 在高通 64 位设备上 SIGILL现象接入后在某款高通或猎户座 64 位机型上启动崩溃崩溃栈里能看到libunity.so的SIGILL或SIGSEGV但换一台老设备又正常。原因Unity 的导出产物里包含多个 ABI 对应的 so 和 IL2CPP 的数据文件。如果你为了包体瘦身把abiFilters只配了armeabi-v7a在只支持 64 位或者对 32 位兼容不完整的系统上系统虽然能安装但运行时会尝试以 x86/arm64 的方式执行 32 位库触发非法指令。解决不要只保留armeabi-v7a。日常真机调试和发布至少保留这两个ndk { abiFilters arm64-v8a, armeabi-v7a }在包体优化时如果你确定所有目标设备都是 64 位 CPU可以只保留arm64-v8a这会省下不少体积但必须先做设备抽样测试而不是拍脑袋决定。还有一种情况是你把useLegacyPackaging设成了falseAndroid 会选择提取 so 而非直接读取压缩包某些 ROM 对提取路径处理有问题也会导致启动时找不到库。改成true通常能规避一大部分玄学。5.4 Android 11 分区存储下访问 /storage/emulated/0 失败现象Unity 里写死路径/storage/emulated/0/Android/data/com.your.app/files/xxx在 Android 9 上读写正常Android 11 上偶发FileNotFoundException或者读出来是空文件。原因从 Android 10 开始强制分区存储Android 11 进一步收紧了应用对外部共享目录的访问。通过绝对路径直接访问其他应用 data 目录会被拒绝即使路径指向的是自己包名下也可能因为你用了旧的WRITE_EXTERNAL_STORAGE权限模式而失效。解决放弃硬编码绝对路径。Unity 侧读取文件时不要直接拼/storage/emulated/0/...而是通过原生桥接拿到标准目录之后再拼接。最简单的做法是用 Unity 自带的Application.persistentDataPath在 Android 上它对应的就是应用专属目录系统默认放行。如果你需要把文件放到用户可见的公共目录比如下载目录那是另一套 MediaStore 逻辑不要走绝对路径。总之凡是遇到路径相关的奇怪读写失败先检查是不是踩了分区存储的边界。5.5 从后台回来 Unity 黑屏时间缩放与生命周期混在一起现象Unity 页面切后台再回来屏幕全黑但声音还在播放或者画面停在最后一帧整个场景的动画像被冻结了。原因这里有两个常见因素叠加。一是 UnityPlayer 的pause()/resume()没跟上 Activity 生命周期Surface 被系统回收后 Unity 没有重建渲染目标。二是有人在切后台时把Time.timeScale直接设成了 0导致 Unity 里的独立脚本还在跑但所有动画和物理都停了看起来像整个场景消失了一样。解决先查生命周期再查 timeScale。生命周期问题参考 4.1 里的自定义 Activity 写法确保onPause/onResume成对调用。timeScale 的问题则是在 Unity 侧统一封装一个切后台事件不要直接改 timeScale而是只暂停需要暂停的 MonoBehaviourvoid OnApplicationPause(bool paused) { if (paused) { // 不要直接 Time.timeScale 0f // 改为逐个暂停业务组件或使用自定义的暂停状态 } }OnApplicationPause是 Unity 提供的标准回调和 Android 的onPause时序不完全一致需要在原生侧收到 onPause 后主动调 Unity 的暂停逻辑而不是只靠 Unity 自己。黑屏问题排查顺序很简单先看有没有声音有声音说明 libunity 和 Audio 还在工作问题在 Surface 或渲染线程没声音说明整个 Unity 运行时都可能挂了去 Logcat 找 crash 栈。6. 最后再折腾验证、性能与升级路线接入能跑通之后不要急着庆祝还有三件事值得花时间做验证帧率、查冷启动时间、想清楚后续升级路线。这里给一个我常用的验证手段。Unity 侧写一个最简单的性能记录脚本using System.IO; using UnityEngine; public class FpsLogger : MonoBehaviour { void Update() { if (Time.frameCount % 60 0) { string text (1f / Time.deltaTime).ToString(0.0); File.WriteAllText(Application.persistentDataPath /fps.txt, text); } } }跑一段业务后用 adb 把这个文件拉出来adb pull /sdcard/Android/data/com.your.app/files/fps.txt ./fps.txt这个方式比直接在 PC 上连 profiler 方便适合现场侧真机验证。注意Application.persistentDataPath对应的就是getExternalFilesDir的路径不需要额外权限也不会被分区存储卡住。如果你发现帧率在原生页面跳转后骤降先检查是不是 Unity 的QualitySettings里的 vsync 和 Android 的Choreographer打架把 Unity 的垂直同步计数设为 “Don’t Sync” 再测一次往往能解开一个性能谜团。冷启动时间可以打点记录从原生点击按钮到UnityPlayer第一次渲染帧出现这段时间主要由 IL2CPP 初始化和场景加载构成。如果超过 2 秒优先做Player Settings里的Managed Stripping Level调整再考虑场景拆分成 AB。升级 Unity 版本时不要直接拿旧工程打开新编辑器先在分支上导出一版空场景验证 AAR 兼容性。Unity 新版本里有些渲染特性比如 GPU Skinning需要设备支持 Vulkan 或 OpenGL ES 3.1老机型上不提前验证会在嵌入后直接黑屏。我早期接手这类压缩包时最蠢的做法是把整个 rar 解压后全部塞进 Git结果.gradle、local.properties和一堆临时产物被提交进去团队每个人拉下来都在猜哪里是真正的构建入口。后来我只提交unityLibrary模块和一份构建说明其余全部让 Unity 侧重新导出反而省心得多。框架选型和交付边界比任何一行桥接代码都值得提前讲清楚希望帮到你。本文还有配套的精品资源点击获取
