1. 项目概述为什么Unity与Android交互是移动开发的必修课如果你是一名Unity开发者并且你的项目需要访问手机的硬件功能比如摄像头、传感器、蓝牙、调用系统级的API如通知、分享、应用内支付或者需要集成第三方Android SDK比如广告、登录、地图那么“Unity与Android交互”就是你绕不开的核心技术。这不仅仅是简单的打包一个APK而是打通Unity的C#世界与Android的Java/Kotlin世界让两个独立的“王国”能够顺畅通信。而SO库Shared Object Library即动态链接库的打包则是这个交互过程中性能与功能扩展的关键一环尤其是在需要集成C/C编写的原生代码比如算法库、音视频编解码库时。我见过太多项目前期功能开发飞快一到与Android原生交互就卡壳要么是通信失败要么是SO库加载崩溃要么是打包后功能丢失。这些问题往往在项目后期集中爆发调试起来极其痛苦。因此与其事后补救不如在项目架构之初就系统地掌握这套交互与打包的完整流程。这篇文章我将结合我过去在多个商业项目中踩过的坑和总结的经验为你拆解从交互原理、代码编写、到SO库集成与最终打包上线的全链路实战指南。无论你是想调用一个简单的Toast消息还是集成复杂的AI推理引擎这里面的核心逻辑都是相通的。2. 交互原理深度解析Unity与Android如何“握手”Unity应用在Android上运行时本质上是一个特殊的Android应用。它的入口是一个UnityPlayerActivity。我们的交互就是让Unity的C#脚本能够调用到这个Activity及其背后整个Android系统里的Java方法反之亦然。理解这个底层机制是解决一切奇怪问题的前提。2.1 核心桥梁AndroidJavaClass与AndroidJavaObjectUnity提供了AndroidJavaClass和AndroidJavaObject这两个类作为C#与Java世界通信的桥梁。你可以把它们理解为Java世界的“反射”机制在C#中的实现。AndroidJavaClass用于访问静态static的类、字段和方法。比如你想调用android.widget.Toast这个类来显示一个提示。AndroidJavaObject用于访问非静态的实例对象、字段和方法。比如你获取了一个当前Activity的实例然后调用它的finish()方法。一个最简单的调用Android Toast的例子using UnityEngine; public class AndroidToast : MonoBehaviour { void Start() { ShowAndroidToast(Hello from Unity!); } void ShowAndroidToast(string message) { // 获取当前Activity的上下文 AndroidJavaClass unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer); AndroidJavaObject currentActivity unityPlayer.GetStaticAndroidJavaObject(currentActivity); // 在Android UI线程中运行 currentActivity.Call(runOnUiThread, new AndroidJavaRunnable(() { // 调用Android SDK的Toast AndroidJavaClass toastClass new AndroidJavaClass(android.widget.Toast); AndroidJavaObject context currentActivity.CallAndroidJavaObject(getApplicationContext); AndroidJavaObject toast toastClass.CallStaticAndroidJavaObject(makeText, context, message, toastClass.GetStaticint(LENGTH_SHORT)); toast.Call(show); })); } }注意Android的UI操作如Toast、对话框必须在主线程UI线程执行。直接在其他线程调用会导致应用崩溃。上面例子中的runOnUiThread是关键。2.2 更优雅的交互方式Android Java Plugin对于简单的、一次性的调用使用上述方式没问题。但对于复杂的、高频的交互或者需要自定义Android端逻辑时我们更推荐使用Android Java Plugin。这种方式允许你将编译好的Java代码打包成JAR或AAR文件或Android Library项目直接放入Unity的Assets/Plugins/Android目录下。Unity在打包时会自动将其合并到最终的APK中。为什么推荐Plugin方式代码组织清晰Java逻辑独立成库与C#脚本解耦。性能更优避免了高频次使用AndroidJavaObject带来的反射开销。功能强大可以方便地创建自定义的Android Activity、Service、BroadcastReceiver并定义复杂的接口。便于维护Android端的代码可以用Android Studio进行专业开发、调试和版本管理。Plugin的基本结构 在你的Unity项目Assets文件夹下创建如下结构Assets/ └── Plugins/ └── Android/ ├── YourAndroidLibrary.aar (或 yourLibs.jar) ├── AndroidManifest.xml (可选用于声明权限、Activity等) └── res/ (可选存放资源文件)2.3 双向通信从Android回调Unity交互不是单向的。很多时候Android端处理完事件如支付成功、传感器数据更新后需要通知回Unity。这需要通过Unity提供的UnityPlayer.UnitySendMessage方法来实现。在Android端Java代码import com.unity3d.player.UnityPlayer; public class MyNativePlugin { // 定义一个静态方法供C#调用 public static void triggerCallbackToUnity() { // 参数1: Unity场景中的GameObject名称 // 参数2: 该GameObject上挂载的脚本的方法名 // 参数3: 要传递的字符串消息 UnityPlayer.UnitySendMessage(AndroidCallbackReceiver, OnNativeMessage, Data from Android); } }在Unity端C#脚本using UnityEngine; public class AndroidCallbackReceiver : MonoBehaviour { // 这个方法名必须与Android端调用时传递的第二个参数完全一致 public void OnNativeMessage(string message) { Debug.Log(Received from Android: message); // 在这里处理来自Android的消息 } }你需要确保场景中存在一个名为AndroidCallbackReceiver的GameObject并且其上挂载了包含OnNativeMessage方法的脚本。实操心得UnitySendMessage虽然方便但它基于反射查找方法和GameObject有一定性能开销且是非类型安全的方法名拼写错误只有在运行时才会报错。对于高性能或复杂的回调建议使用更高级的方式如通过AndroidJavaProxy建立接口回调但这需要更复杂的设置。3. SO库原生库集成全攻略当你的功能涉及高性能计算、硬件加速如OpenGL ES、Vulkan、或集成现有的C/C库时就需要使用SO库。SO库是编译好的二进制文件直接由CPU执行效率远高于通过Java或C#解释执行的代码。3.1 SO库是什么ABI又是什么SO库.so文件在Linux/Android系统中相当于Windows的.dll文件是动态链接库。它包含了编译好的机器码。ABIApplication Binary Interface应用程序二进制接口。不同的CPU架构如ARM, x86有不同的指令集因此需要为每种架构编译对应的SO库。常见的Android ABI有armeabi-v7a: 32位ARM架构目前存量设备最多。arm64-v8a: 64位ARM架构现代手机的主流架构性能更好。x86/x86_64: 主要用于模拟器和少数Intel处理器的平板。mips/mips64: 已逐渐被淘汰。关键决策你需要为你的应用支持哪些ABI支持越多APK体积越大。通常建议至少支持arm64-v8a和armeabi-v7a以覆盖绝大多数设备。可以通过Player Settings中的Target Architectures来选择。3.2 在Unity中集成SO库将SO库集成到Unity项目中非常简单只需将其放入正确的目录即可。获取SO库可能是你自己用NDK编译的也可能是第三方SDK提供的。放置目录在Unity项目的Assets/Plugins/Android目录下为每个ABI创建一个以ABI名称命名的文件夹然后将对应的.so文件放进去。Assets/ └── Plugins/ └── Android/ ├── libs/ (可放JAR但非必须) ├── arm64-v8a/ │ └── libYourNativeLib.so ├── armeabi-v7a/ │ └── libYourNativeLib.so └── x86/ (如果支持模拟器调试) └── libYourNativeLib.so在C#中调用Unity会自动加载Plugins/Android下的SO库。你需要使用DllImport特性来声明和调用其中的C函数。using System.Runtime.InteropServices; using UnityEngine; public class NativePluginWrapper : MonoBehaviour { // 声明SO库中的函数 // EntryPoint指定C函数名 CharSet指定字符串编码 [DllImport(YourNativeLib)] private static extern int NativeAdd(int a, int b); [DllImport(YourNativeLib)] private static extern void NativeLog(string message); void Start() { int result NativeAdd(5, 3); Debug.Log($Native add result: {result}); NativeLog(Calling from Unity C#); } }注意DllImport中的库名是YourNativeLib而不是libYourNativeLib.so。链接器会自动处理前缀(lib)和后缀(.so)。3.3 通过Android Plugin (JAR/AAR) 间接使用SO库更常见的场景是第三方SDK如某些人脸识别、语音SDK会提供一个AAR或JAR文件其中已经封装好了Java接口并且内部包含了SO库。对于这种情况你只需要将AAR/JAR文件放入Assets/Plugins/Android目录即可。Unity在打包时会自动解压AAR并将其中的SO库、资源、清单文件合并到最终APK中。处理AAR中的SO库冲突如果你集成了多个第三方SDK它们的AAR可能包含了相同ABI但不同版本的相同SO库例如都包含了不同版本的libc_shared.so这会导致冲突打包失败。解决方法通常是在Assets/Plugins/Android目录下创建一个名为mainTemplate.gradle文件需要开启Gradle自定义在其中排除重复的库。示例mainTemplate.gradle片段android { packagingOptions { pickFirst lib/arm64-v8a/libc_shared.so pickFirst lib/armeabi-v7a/libc_shared.so // 或者使用exclude排除特定的库 // exclude lib/armeabi-v7a/libSomeProblematicLib.so } }4. 打包实战从Unity到APK/AAB的完整流程理解了交互和集成打包就是最后一道工序。Unity的Android打包看似一键完成但背后的配置选项决定了应用的兼容性、性能和体积。4.1 基础环境配置在开始打包前必须确保你的开发环境正确设置安装Unity Hub和对应版本的Unity编辑器建议使用LTS长期支持版本如2022.3 LTS稳定性更高。安装Android Build Support模块在Unity Hub中安装Unity时务必勾选Android Build Support它包含了必要的SDK、NDK、JDK等工具链。配置JDK、SDK、NDK路径打开Unity进入Edit - Preferences - External Tools。JDKUnity内置的或你自己安装的JDK 8或11推荐。路径类似C:\Program Files\Unity\Hub\Editor\2022.3.0f1\Editor\Data\PlaybackEngines\AndroidPlayer\OpenJDK。Android SDKUnity内置或指定你通过Android Studio安装的SDK路径。确保SDK Platform Tools版本足够新。NDK这是SO库编译和链接的关键。Unity会自带一个推荐的NDK版本。除非你有特殊需求如需要特定版本的C特性否则强烈建议使用Unity推荐的NDK版本这是避免编译错误的最简单方法。踩坑记录我曾因为使用了比Unity推荐版本更高的NDK导致编译IL2CPP时出现奇怪的C标准库链接错误折腾了大半天。教训就是在Unity Android开发中工具链版本“不求最新但求最配”。4.2 Player Settings关键配置解析打开File - Build Settings选择Android平台点击Player Settings这里面的配置至关重要。4.2.1 分辨率与图标Resolution and PresentationDefault Orientation根据你的游戏类型选择横屏游戏选Landscape Left。Allowed Orientations for Auto Rotation如果你的游戏支持旋转在这里勾选。4.2.2 图标Icon准备一套符合Android规范的多尺寸图标覆盖从ldpi到xxxhdpi。Unity可以自动缩放但为了最佳效果建议提供原始尺寸。4.2.3 发布设置Publishing Settings这是配置交互和SO库相关的核心区域。Package Name应用的唯一标识符格式如com.YourCompany.YourGame。一旦发布绝对不能修改。VersionVersion CodeVersion是给用户看的版本名如1.2.0Version Code是整数版本号每次上传商店必须递增。Minimum API Level应用支持的最低Android版本。设置太低会限制新API的使用太高会丢失部分用户。需要权衡。目前API Level 23 (Android 6.0)是一个比较安全的底线可以支持绝大多数设备并涵盖动态权限申请。Target API Level应用目标适配的API级别。Google Play要求必须设置为最新主流API版本目前是API 34。设置正确可以确保应用能利用最新的系统优化和安全特性。Scripting BackendMono使用.NET框架编译速度快脚本体积小但执行效率较低且不支持64位在Google Play 64位要求下已逐渐淘汰。IL2CPP将C#代码转换为C代码再编译为本地二进制。这是当前的主流和强制推荐选项。它提供了更好的性能、更好的兼容性尤其是64位支持并且能有效防止代码被轻易反编译。选择IL2CPP是支持64位ABIarm64-v8a的前提。Target Architectures选择你的应用支持的CPU架构。必须勾选ARM64以符合Google Play的64位要求。同时可以勾选ARMv7以兼容旧设备。除非你有特殊需求否则不要勾选x86系列它们会显著增加APK体积而用户极少。Enable ARMv9 Security Features如果目标架构包含ARM64且你的应用有高安全需求可以考虑开启。4.2.4 纹理压缩Texture Compression这是一个影响包体和兼容性的重要设置。ETC2适用于支持OpenGL ES 3.0的设备API Level 18以上。它是默认且推荐的格式因为它支持Alpha通道透明。ASTC更先进的压缩格式压缩比和画质更好但需要设备硬件支持。如果你的Minimum API Level设得较高如24以上且目标设备较新可以考虑使用ASTC。Don‘t Override如果你在纹理导入设置中为每个纹理单独指定了压缩格式可以选此项。注意事项如果你选择了ETC2但需要支持不支持OpenGL ES 3.0的老设备API Level 18就必须在ETC2 Fallback中选择一个回退格式如32-bit这会导致包体变大。因此合理设置最低API级别可以避免这个问题。4.3 构建系统Build System选择与导出项目在Build Settings窗口中Build System选项决定了Unity如何生成最终的APK。Gradle (推荐)这是Unity默认且功能最强大的构建系统。它使用Gradle构建脚本支持更灵活的配置如自定义build.gradle、构建App BundleAAB以及方便地导出项目到Android Studio进行深度调试。Internal (已弃用)旧版内部构建系统功能有限不再推荐使用。为什么强烈推荐Gradle支持AABGoogle Play官方推荐的发布格式可以生成针对不同设备配置的优化APK减小用户下载体积。高度可定制你可以通过修改mainTemplate.gradle或launcherTemplate.gradle等文件添加依赖、配置ProGuard/R8混淆、修改构建变体等这是集成复杂第三方SDK的必备技能。便于调试可以导出完整的Gradle项目到Android Studio利用Android Studio强大的日志、调试器和性能分析工具。导出项目到Android Studio的步骤在Build Settings中选择Build System为Gradle。勾选Export Project。点击Export按钮选择一个空文件夹。用Android Studio打开导出的项目文件夹。在Android Studio中你可以像开发原生Android应用一样进行编译、运行和调试。这对于排查复杂的原生层Java/Kotlin或JNI问题非常有用。4.4 执行构建APK vs AAB构建APK直接点击Build会生成一个或多个APK文件如果你启用了Split APKs by target architecture。适合用于内部测试、直接安装或上传到某些第三方渠道。构建App Bundle (AAB)在Build Settings中勾选Build App Bundle (Google Play)然后点击Build。这会生成一个.aab文件。AAB是上传到Google Play商店的唯一官方格式。你将它上传后Google Play会为用户的设备动态生成最优的APK。关于拆分APKSplit APKs 在Player Settings - Publishing Settings中有两个重要选项Split Application Binary将应用资源如图形、视频拆分到单独的OBB文件中。这可以减小初始APK大小但需要处理OBB文件的下载和加载Unity有相关API。对于资源庞大的游戏非常有用。Split APKs by target architecture为每个目标CPU架构如arm64-v8a, armeabi-v7a生成独立的APK。当与AAB一起使用时Google Play会自动为用户的设备分配合适的架构APK避免将所有架构的SO库都打包进一个APK从而显著减小下载体积。这是最佳实践务必启用。5. 高级配置与疑难杂症排查即使按照上述步骤操作在实际项目中你仍会遇到各种问题。下面是一些常见“坑点”及其解决方案。5.1 SO库加载失败java.lang.UnsatisfiedLinkError这是最常见的问题通常表现为应用启动时立刻崩溃日志中报错找不到本地方法或无法加载库。可能原因及解决方案问题现象可能原因解决方案dlopen failed: library “libxxx.so” not found1. SO库未放入正确的ABI文件夹。2. SO库依赖的其他SO库不存在。3. SO库是为错误的ABI编译的如x86库运行在ARM设备。1. 检查Assets/Plugins/Android下的目录结构是否正确。2. 使用readelf -d libYourNativeLib.sojava.lang.UnsatisfiedLinkError: No implementation found for native methodC#中DllImport声明的函数签名与SO库中的C/C函数签名不匹配。1. 检查C函数是否被extern “C”包裹以防止名称修饰Name Mangling。2. 检查函数名、参数类型、返回类型是否完全一致。注意字符串传递char*vsString和编码CharSet。3. 使用nm -D libYourNativeLib.soUnix查看导出的函数名。加载成功但调用崩溃内存管理问题如访问已释放的内存、缓冲区溢出、或线程安全问题在非JNI线程调用JNI函数。1. 使用Android Studio的NDK调试功能或adb logcat捕获原生崩溃日志。2. 检查JNI代码中全局引用Global Reference的创建和删除是否正确避免内存泄漏。3. 确保在正确的线程调用JNI函数。复杂的原生操作建议在独立线程进行通过回调通知Java/Unity。5.2 版本兼容性与冲突NDK版本冲突如前所述坚持使用Unity推荐的NDK版本。Android Gradle Plugin (AGP) 版本冲突当你自定义mainTemplate.gradle或集成第三方AAR时可能会遇到AGP版本不兼容。你可以在mainTemplate.gradle中指定一个与你的Gradle版本兼容的AGP版本。buildscript { repositories { google() mavenCentral() } dependencies { // 使用一个较新且稳定的版本如7.4.2 classpath com.android.tools.build:gradle:7.4.2 } }Java版本冲突确保你的JDK版本与AGP和Gradle兼容。Unity 2022 LTS通常与JDK 11配合良好。5.3 构建优化与包体瘦身代码剥离Code Stripping在Player Settings - Publishing Settings - Minify中对于Release构建启用Minify使用ProGuard或R8。这可以移除未使用的代码显著减小包体。但必须为所有通过反射调用的类、方法、字段添加混淆保留规则否则会导致运行时崩溃。规则通常写在proguard-user.txt文件中并放在Assets/Plugins/Android目录下。纹理优化使用合适的纹理压缩格式ETC2, ASTC和尺寸。避免使用过大的纹理。启用引擎代码剥离Engine Code Stripping在Player Settings - Publishing Settings中可以启用此选项移除Unity引擎中未使用的模块代码。分析构建报告构建完成后Unity会生成一个构建报告BuildReport。仔细查看其中哪些资源、代码占用了大部分空间进行针对性优化。5.4 调试技巧ADB Logcat这是最强大的调试工具。在命令行使用adb logcat -s Unity可以过滤Unity的日志。使用adb logcat *:E查看所有错误日志。Android Studio Profiler如果你导出了项目到Android Studio可以使用其Profiler工具分析CPU、内存、网络和能耗这对于优化性能至关重要。Development Build在Build Settings中勾选Development Build并启用Script Debugging和Profiler。这样你可以在Unity编辑器中连接运行在设备上的游戏进行实时调试和性能分析。查看导出的Gradle项目当遇到复杂的构建错误时导出项目到Android Studio然后在Android Studio中执行Build - Make Project通常能得到更详细、更准确的错误信息。6. 实战案例集成一个简单的原生计算库让我们通过一个完整的微型案例将上述所有知识点串联起来。目标用C编写一个简单的加法函数编译成SO库在Android上通过Unity调用。步骤1编写C原生代码创建一个文件native-lib.cpp#include jni.h #include string extern C JNIEXPORT jint JNICALL Java_com_yourcompany_yourapp_NativeLib_add(JNIEnv* env, jobject /* this */, jint a, jint b) { return a b; }注意函数命名规范Java_包名_类名_方法名。这里我们假设在Android端会有一个com.yourcompany.yourapp.NativeLib类其中有一个add方法。步骤2使用NDK编译SO库你需要安装Android NDK。使用命令行或CMake进行编译。这里以命令行简化示例实际项目建议用CMake或Android.mk# 假设NDK路径为 $NDK_HOME $NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/aarch64-linux-android21-clang \ -shared -o libNativeMath.so native-lib.cpp \ -I$NDK_HOME/sysroot/usr/include/jni.h \ -I$NDK_HOME/sysroot/usr/include/aarch64-linux-android这会生成libNativeMath.so针对arm64-v8a。你需要为每个目标ABI编译一个版本。步骤3创建Android端Java桥接类在Android Studio或任何文本编辑器中创建NativeLib.javapackage com.yourcompany.yourapp; public class NativeLib { static { System.loadLibrary(NativeMath); // 加载 libNativeMath.so } public static native int add(int a, int b); // 声明本地方法 }将这个Java文件编译成JAR或者更好的方式是创建一个Android Library模块将其与SO库一起打包成AAR。步骤4在Unity中集成将编译好的libNativeMath.so文件按照ABI放入Assets/Plugins/Android/[abi]/目录。将包含NativeLib类的JAR或AAR文件放入Assets/Plugins/Android目录。在Unity C#脚本中调用using UnityEngine; public class NativeCalculator : MonoBehaviour { void Start() { // 方式一通过AndroidJavaClass调用Java桥接类 AndroidJavaClass nativeLibClass new AndroidJavaClass(com.yourcompany.yourapp.NativeLib); int result nativeLibClass.CallStaticint(add, 10, 20); Debug.Log($Result via Java: {result}); // 方式二如果你熟悉JNI也可以直接通过DllImport调用SO库不推荐更复杂 // 这需要你直接声明C函数并处理JNIEnv等参数。 } }步骤5配置与打包按照第4章的内容正确设置Player Settings特别是Scripting Backend为IL2CPPTarget Architectures包含arm64-v8a使用Gradle构建系统最后构建APK或AAB。通过这个完整的流程你就完成了一次从原生代码编写、编译、桥接到Unity集成和打包的完整闭环。掌握这个流程你就能应对绝大多数Unity与Android原生交互以及SO库集成的需求。记住耐心和细致的日志分析是解决这类跨平台问题的关键。
