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与AndroidJavaObject

Unity提供了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.GetStatic<AndroidJavaObject>("currentActivity"); // 在Android UI线程中运行 currentActivity.Call("runOnUiThread", new AndroidJavaRunnable(() => { // 调用Android SDK的Toast AndroidJavaClass toastClass = new AndroidJavaClass("android.widget.Toast"); AndroidJavaObject context = currentActivity.Call<AndroidJavaObject>("getApplicationContext"); AndroidJavaObject toast = toastClass.CallStatic<AndroidJavaObject>("makeText", context, message, toastClass.GetStatic<int>("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方式？

1. 代码组织清晰：Java逻辑独立成库，与C#脚本解耦。
2. 性能更优：避免了高频次使用AndroidJavaObject带来的反射开销。
3. 功能强大：可以方便地创建自定义的Android Activity、Service、BroadcastReceiver，并定义复杂的接口。
4. 便于维护：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文件，是动态链接库。它包含了编译好的机器码。
• ABI（Application 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项目中非常简单，只需将其放入正确的目录即可。

1. 获取SO库：可能是你自己用NDK编译的，也可能是第三方SDK提供的。
2. 放置目录：在Unity项目的Assets/Plugins/Android目录下，为每个ABI创建一个以ABI名称命名的文件夹，然后将对应的.so文件放进去。

Assets/ └── Plugins/ └── Android/ ├── libs/ (可放JAR，但非必须) ├── arm64-v8a/ │ └── libYourNativeLib.so ├── armeabi-v7a/ │ └── libYourNativeLib.so └── x86/ (如果支持模拟器调试) └── libYourNativeLib.so

3. 在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 基础环境配置

在开始打包前，必须确保你的开发环境正确设置：

1. 安装Unity Hub和对应版本的Unity编辑器：建议使用LTS（长期支持）版本，如2022.3 LTS，稳定性更高。
2. 安装Android Build Support模块：在Unity Hub中安装Unity时，务必勾选Android Build Support，它包含了必要的SDK、NDK、JDK等工具链。
3. 配置JDK、SDK、NDK路径：打开Unity，进入Edit -> Preferences -> External Tools。
   • JDK：Unity内置的或你自己安装的JDK 8或11（推荐）。路径类似C:\Program Files\Unity\Hub\Editor\2022.3.0f1\Editor\Data\PlaybackEngines\AndroidPlayer\OpenJDK。
   • Android SDK：Unity内置或指定你通过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 Presentation）

• Default 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。一旦发布，绝对不能修改。
• Version&Version Code：Version是给用户看的版本名（如1.2.0），Version Code是整数版本号，每次上传商店必须递增。
• Minimum API Level：应用支持的最低Android版本。设置太低会限制新API的使用，太高会丢失部分用户。需要权衡。目前API Level 23 (Android 6.0)是一个比较安全的底线，可以支持绝大多数设备并涵盖动态权限申请。
• Target API Level：应用目标适配的API级别。Google Play要求必须设置为最新主流API版本（目前是API 34）。设置正确可以确保应用能利用最新的系统优化和安全特性。
• Scripting Backend：
  • Mono：使用.NET框架，编译速度快，脚本体积小，但执行效率较低，且不支持64位（在Google Play 64位要求下已逐渐淘汰）。
  • IL2CPP：将C#代码转换为C++代码再编译为本地二进制。这是当前的主流和强制推荐选项。它提供了更好的性能、更好的兼容性（尤其是64位支持），并且能有效防止代码被轻易反编译。选择IL2CPP是支持64位ABI（arm64-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 Bundle（AAB）以及方便地导出项目到Android Studio进行深度调试。
• Internal (已弃用)：旧版内部构建系统，功能有限，不再推荐使用。

为什么强烈推荐Gradle？

1. 支持AAB：Google Play官方推荐的发布格式，可以生成针对不同设备配置的优化APK，减小用户下载体积。
2. 高度可定制：你可以通过修改mainTemplate.gradle或launcherTemplate.gradle等文件，添加依赖、配置ProGuard/R8混淆、修改构建变体等，这是集成复杂第三方SDK的必备技能。
3. 便于调试：可以导出完整的Gradle项目到Android Studio，利用Android Studio强大的日志、调试器和性能分析工具。

导出项目到Android Studio的步骤：

1. 在Build Settings中，选择Build System为Gradle。
2. 勾选Export Project。
3. 点击Export按钮，选择一个空文件夹。
4. 用Android Studio打开导出的项目文件夹。
5. 在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。

关于拆分APK（Split 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

这是最常见的问题，通常表现为应用启动时立刻崩溃，日志中报错找不到本地方法或无法加载库。

可能原因及解决方案：

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 构建优化与包体瘦身

1. 代码剥离（Code Stripping）：在Player Settings -> Publishing Settings -> Minify中，对于Release构建，启用Minify（使用ProGuard或R8）。这可以移除未使用的代码，显著减小包体。但必须为所有通过反射调用的类、方法、字段添加混淆保留规则，否则会导致运行时崩溃。规则通常写在proguard-user.txt文件中，并放在Assets/Plugins/Android目录下。
2. 纹理优化：使用合适的纹理压缩格式（ETC2, ASTC）和尺寸。避免使用过大的纹理。
3. 启用引擎代码剥离（Engine Code Stripping）：在Player Settings -> Publishing Settings中，可以启用此选项移除Unity引擎中未使用的模块代码。
4. 分析构建报告：构建完成后，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.java：

package 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中集成

1. 将编译好的libNativeMath.so文件按照ABI放入Assets/Plugins/Android/[abi]/目录。
2. 将包含NativeLib类的JAR或AAR文件放入Assets/Plugins/Android目录。
3. 在Unity C#脚本中调用：

using UnityEngine; public class NativeCalculator : MonoBehaviour { void Start() { // 方式一：通过AndroidJavaClass调用Java桥接类 AndroidJavaClass nativeLibClass = new AndroidJavaClass("com.yourcompany.yourapp.NativeLib"); int result = nativeLibClass.CallStatic<int>("add", 10, 20); Debug.Log($"Result via Java: {result}"); // 方式二：如果你熟悉JNI，也可以直接通过DllImport调用SO库（不推荐，更复杂） // 这需要你直接声明C函数，并处理JNIEnv等参数。 } }

步骤5：配置与打包按照第4章的内容，正确设置Player Settings（特别是Scripting Backend为IL2CPP，Target Architectures包含arm64-v8a），使用Gradle构建系统，最后构建APK或AAB。

通过这个完整的流程，你就完成了一次从原生代码编写、编译、桥接到Unity集成和打包的完整闭环。掌握这个流程，你就能应对绝大多数Unity与Android原生交互以及SO库集成的需求。记住，耐心和细致的日志分析是解决这类跨平台问题的关键。