Unity调用Android NDK动态库全流程：从原理到实战避坑指南

1. 项目概述：为什么Unity开发者需要掌握NDK与动态库？

如果你是一个Unity开发者，尤其是在移动平台深耕Android游戏或应用，那么“性能瓶颈”和“功能扩展”这两个词一定不陌生。Unity的C#脚本在开发效率上无与伦比，但面对密集计算、复杂算法、硬件底层操作（如特定图像处理、音频编解码）或复用已有的C/C++库时，其性能往往捉襟见肘。这时，一个强大的武器就摆在我们面前：通过Android NDK（Native Development Kit）编译C/C++代码为动态链接库（.so文件），然后在Unity中调用它。

这不仅仅是“高级技巧”，而是解决实际工程问题的刚需。想象一下，你需要集成一个由算法团队用C++编写的高效人脸识别库，或者一个用C优化过的物理模拟模块，又或者需要直接操作某些Android硬件特性，这些场景下，纯C#要么无法实现，要么效率低下。直接调用.so动态库，就成了连接Unity高效开发与C++高性能计算的唯一桥梁。

然而，从搜索热词如“unity webgl初始化很久”、“android studio怎么设置中文？”可以看出，很多开发者在环境配置和基础概念上就遇到了巨大障碍。NDK配置、JNI接口、ABI适配、打包发布……每一步都可能藏着深坑。本文将从零开始，以一个完整的NDK示例项目为核心，拆解Unity调用Android .so动态库的全流程。我不会只给你一堆代码，而是会重点解释每个步骤背后的“为什么”，并分享我趟过的那些坑，目标是让你看完就能动手，做出来就能用上。

2. 核心原理与架构设计：C#、Java、C++的三方对话

在深入实操之前，我们必须理清一个根本问题：Unity的C#脚本，是如何跨越层层障碍，最终调用到用C++编写的.so库中的函数的？这个过程涉及三个“世界”的通信：

1. C#世界 (Unity Runtime)：我们的游戏逻辑所在地。
2. Java世界 (Android JVM)：Android系统的核心，通过Java Native Interface (JNI) 管理本地代码。
3. C++世界 (Native Layer)：.so动态库运行的地方，提供极致性能。

它们之间的对话并非直接进行，而是遵循一套标准的“协议”，我们可以将其理解为一次“跨国三方通话”，C#是发起人，Java是翻译官兼接线员，C++是最终的执行者。

2.1 通信链条拆解

整个调用链条可以清晰地划分为以下几个步骤：

步骤一：C# 发起呼叫Unity的C#脚本无法直接识别.so文件。它首先需要通过Android的Java接口来加载本地库。在Unity中，我们使用AndroidJavaClass和AndroidJavaObject来与Android的Java层进行交互。这相当于C#用Android SDK提供的“电话”拨通了Java世界的号码。

步骤二：Java 接收并转发在Java层，我们需要创建一个“桥梁”类。这个类有两个关键作用：

1. 加载本地库：使用System.loadLibrary(“YourLibraryName”)语句。这行代码会通知Android运行时，去系统的库路径下寻找名为libYourLibraryName.so的文件并加载它。
2. 声明本地方法：使用native关键字声明方法，例如public static native int calculateSomething(int a, int b);。这个方法没有方法体，它只是一个“声明”，告诉JVM：“这个方法的实现在本地库中，名字和签名是xxx，你去找吧。”

步骤三：JNI 建立连接当C#通过Unity的接口调用到Java中声明的那个native方法时，JNI（Java Native Interface）就被激活了。JNI是一套标准的编程接口，它定义了Java代码如何调用本地代码（C/C++），以及本地代码如何回调Java代码。JNI会根据Java中声明的native方法名和参数签名，在已加载的.so文件中寻找对应的C/C++函数。

步骤四：C++ 执行并返回.so库中必须包含一个与Java的native方法签名严格匹配的C/C++函数。JNI找到了这个函数，并将控制权交给它。C++函数执行其计算逻辑，然后通过JNI环境将结果返回给Java层，再经由Java层最终返回给Unity的C#脚本。

关键理解：Unity C#不直接调用C++。它通过AndroidJavaClass调用一个Java方法，而这个Java方法恰好是一个native方法，这个native方法的实现指向了.so中的C++函数。所以，Java JNI层是这个链条中不可或缺的中间件。很多新手试图绕过Java层，直接让C#调用.so，这是行不通的。

2.2 关键设计决策：为何选择此架构？

你可能会问，为什么这么麻烦？不能简单点吗？这个架构是Android平台安全性和兼容性权衡下的最优解。

• 安全性：Android的沙盒机制要求本地代码必须通过JVM进行加载和管理，JNI提供了可控的交互通道。
• 兼容性：不同的Android设备（ARMv7, ARM64, x86）有不同的CPU架构。.so库需要为每种架构单独编译（即生成不同的ABI版本）。Java层和Unity的打包系统能很好地处理这种多ABI的封装与选择。
• 生态：海量的现有C/C++库都是通过JNI方式提供给Android Java应用使用的。Unity复用这套成熟、标准的机制，是最稳妥、生态支持最好的方案。

理解了这套“三方通话”协议，我们就能明白后续所有实操步骤的目的：搭建这个通信链路，并确保每个环节的信号都能准确无误地传递。

3. 环境准备与工具链配置

工欲善其事，必先利其器。配置开发环境是第一步，也是最容易让人放弃的一步。结合热词中频繁出现的“android studio安装教程”、“ndk配置”、“adb shell”等问题，我将详细说明每个工具的用途和避坑点。

3.1 核心工具清单

1. Unity Hub & Unity Editor：建议使用较新的LTS版本，如2022.3 LTS。确保在安装时勾选了Android Build Support模块（包括Android SDK & NDK Tools）。这是最省心的方式，Unity会帮你管理一个基础版本的NDK。
2. Android Studio：它不仅仅是IDE，更是Android SDK和NDK的官方管理工具。即使你主要用VS或Rider写C#，也需要安装它来获取和更新SDK/NDK。
3. NDK (Native Development Kit)：核心中的核心。它包含了将C/C++代码编译为.so文件所需的交叉编译器、库和工具。
4. 文本编辑器或IDE (用于C++)：如Visual Studio (Windows)、Visual Studio Code 或 CLion。用于编写和调试C++代码。
5. JDK (Java Development Kit)：Unity和Android构建过程需要。建议安装OpenJDK 8或11，并与Unity设置中的JDK路径保持一致。

3.2 详细配置步骤与避坑指南

步骤1：通过Android Studio安装SDK与NDK

1. 下载并安装Android Studio。
2. 打开后，进入Settings/Preferences > Appearance & Behavior > System Settings > Android SDK。
3. 在SDK Platforms选项卡中，勾选你目标Android版本对应的API Level。对于Unity开发，通常选择API Level 24 (Android 7.0)或更高即可，这覆盖了绝大多数现有设备。
4. 切换到SDK Tools选项卡。这里至关重要：
   • 勾选Android SDK Build-Tools（选择一个版本，如34.0.0）。
   • 勾选Android SDK Command-line Tools。
   • 勾选NDK (Side by side)。这是关键！不要用旧的“NDK”，一定要用“Side by side”版本，它允许你同时安装多个NDK版本。选择一个版本，例如25.2.9519653。Unity对不同版本有兼容性要求，稍后我们会关联。
5. 点击Apply进行安装。

步骤2：在Unity中配置路径

1. 打开Unity，进入Edit > Project Settings > Player。
2. 在Player Settings面板中，找到Publishing Settings区域（可能需要展开）。
3. 找到Build区域下的NDK选项。Unity可能已经自动检测到了一个路径（它自带的）。但为了稳定和兼容，我强烈建议手动指定为我们刚从Android Studio安装的NDK路径。
4. 点击输入框右侧的文件夹图标，导航到你的NDK安装目录。通常路径类似：C:\Users\[你的用户名]\AppData\Local\Android\Sdk\ndk\[版本号]或/Users/[你的用户名]/Library/Android/sdk/ndk/[版本号]。
5. 同样，检查JDK和SDK的路径，确保指向正确的安装位置。

实操心得：NDK版本兼容性这是最大的坑之一。Unity版本与NDK版本有严格的对应关系。使用不兼容的NDK可能导致编译失败，错误信息可能晦涩难懂。一个稳妥的方法是：查阅你使用的Unity版本的官方文档，找到其推荐的NDK版本。如果找不到，就使用Unity Hub安装Android模块时自带的那个NDK版本，或者使用Android Studio安装一个较旧的、稳定的版本（如r21e, r23b）。在项目初期就确定并固定NDK版本，能避免后续团队协作和构建服务器上的诸多问题。

步骤3：验证环境打开命令行，分别输入java -version、adb version，确保命令可以正常执行。这能初步判断JDK和Android调试桥是否就绪。

环境配置看似繁琐，但一次配好，受益整个项目周期。接下来，我们将开始创建第一个示例工程。

4. 实战：创建并调用一个简单的NDK动态库

让我们从一个最简单的“Hello World”级示例开始：Unity传递两个整数给C++动态库，C++计算它们的和并返回。这个例子虽小，但涵盖了所有核心环节。

4.1 第一步：创建Android Java“桥梁”类

在Unity项目的Assets目录下，我们通常创建一个Plugins/Android文件夹来存放Android平台专用的插件。在这个文件夹里，我们需要创建一个Java源文件。

1. 在Assets下创建文件夹：Plugins/Android。
2. 在Android文件夹内，创建一个新的文本文件，将其重命名为NativeBridge.java（注意扩展名是.java）。

用文本编辑器打开NativeBridge.java，输入以下内容：

package com.yourcompany.yourapp; // 修改为你自己的包名 import com.unity3d.player.UnityPlayer; public class NativeBridge { // 静态代码块，在类加载时自动执行，用于加载我们的动态库 static { // 加载名为 "NativeCalc" 的动态库。系统会自动添加前缀"lib"和后缀".so" // 最终它会寻找 libNativeCalc.so 文件 System.loadLibrary("NativeCalc"); } // 声明一个本地方法。该方法将在C++中实现。 // public static 使得Unity可以方便地调用它。 public static native int addNumbers(int a, int b); // 一个可选的方法：演示如何从C++回调到Unity public static void sendResultToUnity(String resultMessage) { // 调用Unity中名为"Main Camera"的GameObject上"NativeMessageReceiver"脚本的"OnNativeMessage"方法 UnityPlayer.UnitySendMessage("Main Camera", "OnNativeMessage", resultMessage); } }

代码解析与注意事项：

• 包名 (package)：com.yourcompany.yourapp非常重要！它应该与你Unity项目的Bundle Identifier（在Player Settings中设置）的包名结构一致或在其之下。这是Android系统识别类的基础。
• System.loadLibrary：参数是“NativeCalc”，这意味着我们稍后编译出的.so文件必须命名为libNativeCalc.so。链接器会自动处理前缀和后缀。
• native 方法声明：addNumbers方法没有方法体，只有native关键字和签名。这个签名（方法名、参数类型、返回类型）必须与后续C++函数完全匹配。
• UnitySendMessage：这是Unity提供的从Java（或本地代码）向C#发送消息的便捷方式。它有一些性能开销和限制（参数只能是string），但对于简单的回调通知非常有用。

4.2 第二步：编写C++ JNI实现

接下来，我们需要编写C++代码来实现addNumbers这个native方法。JNI函数的命名有严格的规则：Java_[包名]_[类名]_[方法名]。其中包名中的点.要替换为下划线_。

1. 在项目外部（建议不要在Assets目录内，以免被Unity错误导入），创建一个文件夹用于存放C++源码，例如D:\UnityNDKDemo\NativeCode。
2. 在该文件夹内创建文件native-lib.cpp。

// native-lib.cpp #include <jni.h> // 必须包含JNI头文件 #include <string> // 宏定义，用于简化函数声明，确保函数以C语言方式导出，避免C++的名称修饰 extern "C" { // JNI函数命名: Java_包名_类名_方法名 // 注意：包名中的点(.)要替换为下划线(_) JNIEXPORT jint JNICALL Java_com_yourcompany_yourapp_NativeBridge_addNumbers( JNIEnv *env, // JNI环境指针，提供了操作Java对象、调用Java方法等所有JNI功能 jclass clazz, // 调用该native方法的Java类的引用。因为我们的方法是static的，所以是jclass。 jint a, // 对应Java的int参数 jint b) // 对应Java的int参数 { // 简单的加法计算 int result = a + b; // 演示如何从C++调用Java中的静态方法 jclass bridgeClass = env->FindClass("com/yourcompany/yourapp/NativeBridge"); if (bridgeClass != nullptr) { jmethodID callbackMethod = env->GetStaticMethodID(bridgeClass, "sendResultToUnity", "(Ljava/lang/String;)V"); if (callbackMethod != nullptr) { std::string message = "C++ calculated: " + std::to_string(a) + " + " + std::to_string(b) + " = " + std::to_string(result); jstring jMessage = env->NewStringUTF(message.c_str()); env->CallStaticVoidMethod(bridgeClass, callbackMethod, jMessage); env->DeleteLocalRef(jMessage); // 释放局部引用，避免内存泄漏（在JNI中很重要） } env->DeleteLocalRef(bridgeClass); } return result; // 将结果返回给Java层，最终到达C# } } // extern "C"

代码深度解析：

• extern “C”：这行代码至关重要。C++编译器为了支持函数重载，会对函数名进行“修饰”（mangling），这会导致函数名与我们在Java中声明的名称不一致，JNI链接时就会失败。extern “C”告诉编译器以C语言的方式处理函数名，禁止名称修饰。
• JNI函数签名：JNIEXPORT和JNICALL是宏，确保函数能被JVM正确调用和链接。
• 参数JNIEnv* env：这是JNI编程的核心对象。所有与Java世界的交互（创建对象、调用方法、访问字段）都需要通过它提供的函数来完成。env指针在不同的线程中可能不同，不能缓存它。
• 参数jclass clazz：因为我们的Java方法是static的，所以第二个参数是jclass，代表NativeBridge这个类本身。如果是非静态方法，这里会是jobject obj，代表调用该方法的Java对象实例。
• JNI类型：jint,jstring等是JNI定义的类型，对应Java的基本类型和对象类型。它们在本地代码和Java虚拟机之间安全地传递数据。
• 回调Java方法：代码中演示了如何在C++中通过JNI调用Java静态方法sendResultToUnity。步骤是：FindClass->GetStaticMethodID->CallStaticVoidMethod。获取方法ID时传入的方法签名“(Ljava/lang/String;)V”需要特别小心，一个字符错误都会导致崩溃。可以使用javap -s命令来获取准确的签名。

4.3 第三步：编写CMakeLists.txt构建脚本

我们需要一个工具来告诉编译器如何把native-lib.cpp编译成.so文件。在Android NDK开发中，CMake是目前官方推荐的主流构建系统。

在NativeCode文件夹内，创建CMakeLists.txt文件：

# 设置CMake的最低版本要求 cmake_minimum_required(VERSION 3.18.1) # 定义项目名称 project("NativeCalc") # 添加一个动态库目标，库名称为 NativeCalc，源码为 native-lib.cpp add_library( NativeCalc SHARED native-lib.cpp ) # 查找并链接必要的库。log库用于在Android Logcat中输出日志，便于调试。 find_library( log-lib log ) # 将log库链接到我们的NativeCalc库 target_link_libraries( NativeCalc ${log-lib} )

脚本解读：

• add_library(NativeCalc SHARED ...)：这行指令是关键，它声明我们要构建一个名为NativeCalc的共享库（即.so文件）。SHARED代表动态库。
• target_link_libraries：链接其他库。这里链接了Android的log库，这样我们就可以在C++代码中使用__android_log_print函数向Logcat输出信息，是调试Native代码的必备手段。

4.4 第四步：使用NDK编译生成.so文件

现在，我们有了源码和构建脚本，可以使用NDK的命令行工具进行编译。打开终端（命令行），导航到NativeCode目录。

基础编译命令：

# 假设你的NDK路径是 D:\Android\Sdk\ndk\25.2.9519653 # 在NativeCode目录下执行 # 首先，设置一个变量指向你的NDK目录，方便后续使用 set NDK_PATH=D:\Android\Sdk\ndk\25.2.9519653 # 使用NDK自带的cmake工具进行构建 # -B build 指定构建输出目录为当前目录下的build文件夹 # -DANDROID_ABI=arm64-v8a 指定目标ABI为64位ARM（目前主流手机） # -DANDROID_PLATFORM=android-24 指定目标Android API级别 # -DCMAKE_BUILD_TYPE=Release 指定构建类型为发布模式（优化程度高，体积小） %NDK_PATH%\build\cmake\bin\cmake -B build -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24 -DCMAKE_BUILD_TYPE=Release # 执行编译 %NDK_PATH%\build\cmake\bin\cmake --build build

编译后，你会在NativeCode/build目录下（具体子目录取决于ABI）找到生成的libNativeCalc.so文件。

重要提示：ABI（应用二进制接口）Android设备有多种CPU架构：armeabi-v7a(32位ARM),arm64-v8a(64位ARM，主流),x86,x86_64。为了让你的应用能在不同设备上运行，你需要为所有你打算支持的ABI分别编译.so文件。在真实项目中，你通常会编译一个包含多个ABI版本的“胖”库（fat APK），或者使用Android App Bundle来分发。 你可以修改上面的命令，为不同的ABI分别编译，或者写一个脚本批量处理。例如，将-DANDROID_ABI=arm64-v8a替换为-DANDROID_ABI=armeabi-v7a来编译32位版本。

4.5 第五步：在Unity中集成与调用

1. 放置.so文件：将编译好的libNativeCalc.so文件（注意，对于不同ABI，需要放在不同文件夹下）复制到Unity项目的Assets/Plugins/Android目录中。目录结构必须如下：

   Assets/ Plugins/ Android/ NativeBridge.java libs/ arm64-v8a/ libNativeCalc.so armeabi-v7a/ libNativeCalc.so

   这个结构是Unity打包Android APK时的标准约定。libs文件夹下的子文件夹名必须严格对应ABI名称。

2. 创建C#调用脚本：在Unity中创建一个C#脚本，例如NativeCaller.cs，并将其挂载到场景中的某个GameObject上（如Main Camera）。

using UnityEngine; public class NativeCaller : MonoBehaviour { // 用于接收来自Native层的回调消息 void OnNativeMessage(string message) { Debug.Log("[Unity] Received from Native: " + message); } void Start() { // 尝试调用Native方法 try { // 使用AndroidJavaClass定位我们的Java桥梁类 // 参数必须是完整的包名+类名 AndroidJavaClass bridgeClass = new AndroidJavaClass("com.yourcompany.yourapp.NativeBridge"); // 调用Java静态方法 addNumbers int result = bridgeClass.CallStatic<int>("addNumbers", 5, 7); Debug.Log($"Unity called native addNumbers(5, 7), result = {result}"); } catch (System.Exception e) { Debug.LogError($"Failed to call native method: {e.Message}\n{e.StackTrace}"); } } }

3. 构建与运行：
   • 确保Player Settings中的Package Name(Bundle Identifier) 与Java代码中的包名一致（例如com.yourcompany.yourapp）。
   • 将Android设备连接到电脑并开启USB调试，或者在Unity中设置使用Android模拟器。
   • 在Unity中，选择File > Build Settings，切换平台到Android，然后点击Build And Run。

如果一切顺利，你将在Unity的Console窗口看到类似以下的输出：

[Unity] Received from Native: C++ calculated: 5 + 7 = 12 Unity called native addNumbers(5, 7), result = 12

这表明，调用链路完全打通了：C# -> Java -> JNI -> C++ -> 计算 -> 回调Java -> 回调C#。

5. 进阶技巧与深度优化

掌握了基础调用后，我们面临更实际的问题：如何传递复杂数据（如数组、结构体、字符串）？如何管理内存避免崩溃？如何调试棘手的Native代码？本章节将分享这些进阶内容。

5.1 复杂数据类型的传递

传递和返回字符串：字符串在JNI中处理需要特别小心，因为涉及编码转换和内存管理。

• C++ 接收Java字符串并处理：

  JNIEXPORT jstring JNICALL Java_com_example_NativeBridge_processString(JNIEnv *env, jobject thiz, jstring javaString) { // 1. 将jstring转换为C风格的字符串（UTF-8编码） const char *cStr = env->GetStringUTFChars(javaString, nullptr); if (cStr == nullptr) { return nullptr; // 内存不足 } // 2. 使用cStr进行你的处理... std::string processed = "Processed: "; processed += cStr; // 3. **必须**释放GetStringUTFChars获取的字符串 env->ReleaseStringUTFChars(javaString, cStr); // 4. 将C++字符串转换回jstring返回给Java return env->NewStringUTF(processed.c_str()); }

  注意事项：GetStringUTFChars和NewStringUTF使用的是修改过的UTF-8编码。对于包含非ASCII字符的字符串，考虑使用GetStringChars/ReleaseStringChars（UTF-16）或更现代的GetStringRegion来避免复制。

传递和返回数组：数组是游戏开发中常见的数据结构，如顶点数据、粒子位置等。

• C++ 处理整型数组：

  JNIEXPORT jintArray JNICALL Java_com_example_NativeBridge_doubleArray(JNIEnv *env, jobject thiz, jintArray javaArray) { // 1. 获取数组指针和长度 jsize length = env->GetArrayLength(javaArray); jint *body = env->GetIntArrayElements(javaArray, nullptr); // 2. 处理数据（例如，每个元素乘以2） for (jsize i = 0; i < length; ++i) { body[i] *= 2; } // 3. 释放并提交更改。第三个参数`0`表示将更改复制回Java数组，并释放C++数组。 env->ReleaseIntArrayElements(javaArray, body, 0); // 4. 将修改后的数组返回（实际上就是原数组，但内容已变） return javaArray; // 另一种方式：创建新数组返回 // jintArray newArray = env->NewIntArray(length); // env->SetIntArrayRegion(newArray, 0, length, body); // env->ReleaseIntArrayElements(javaArray, body, JNI_ABORT); // 不复制回原数组 // return newArray; }

  • GetIntArrayElements可能返回一个指向Java数组原始数据的指针，也可能复制一份。isCopy参数可以告诉你是否发生了复制。
  • ReleaseIntArrayElements的第三个参数是模式：
    • 0：复制内容回Java数组，并释放C++数组。
    • JNI_COMMIT：复制内容回Java数组，但不释放C++数组。
    • JNI_ABORT：不复制内容回Java数组，但释放C++数组。

5.2 内存管理与性能优化

1. 局部引用与全局引用：

• 局部引用：在JNI函数内通过JNI函数（如FindClass,NewObject,NewStringUTF）创建的大多数引用都是局部引用。它们在该JNI函数返回后会自动被释放，但如果在一个本地方法中创建了大量局部引用（例如在循环中），可能会超出JVM的局部引用表限制，导致FatalError。此时应使用env->DeleteLocalRef(ref)手动删除不再需要的局部引用，或者在循环结束后调用env->EnsureLocalCapacity(capacity)确保容量。
• 全局引用：如果你需要将一个Java对象（如回调接口）长期保存在C++侧，供后续异步回调使用，必须创建全局引用 (env->NewGlobalRef) 来防止对象被垃圾回收。切记，当不再需要时，必须用env->DeleteGlobalRef释放，否则会导致内存泄漏。

2. 直接缓冲区 (Direct Buffer)：对于需要频繁在Java和C++间传递大量数据（如音频流、图像像素数据）的场景，使用Get<Type>ArrayElements进行复制开销巨大。此时应使用java.nio.ByteBuffer（在C++端对应jobject，通过env->GetDirectBufferAddress获取内存地址）。这允许C++直接读写Java堆外内存，实现了零拷贝，性能极高。Unity中很多底层插件（如音频、图形）都采用这种方式。

5.3 Native代码调试

调试.so库是难点，但并非不可能。

方法一：Logcat日志输出这是最基本也是最常用的方法。在C++代码中包含<android/log.h>，然后使用__android_log_print函数输出日志。

#include <android/log.h> #define LOG_TAG "NativeCalc" #define LOGD(...) __android_log_print(ANDROID_LOG_DEBUG, LOG_TAG, __VA_ARGS__) #define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__) // 在函数中使用 LOGD("addNumbers called with a=%d, b=%d", a, b);

在Android Studio的Logcat窗口中，过滤标签NativeCalc即可看到输出。确保CMakeLists.txt中链接了log库。

方法二：使用Android Studio附加调试器 (LLDB)这是进行断点调试和检查变量值的终极手段。

1. 在C++代码中需要调试的行设置断点（在Android Studio中打开对应的cpp文件）。
2. 在Unity中构建一个Development Build，并勾选Script Debugging和Wait for Managed Debugger（可选）。这会在APK中保留调试符号。
3. 将应用安装到设备或模拟器上并启动。
4. 在Android Studio中，选择Run > Attach Debugger to Android Process，选择你的Unity应用进程。
5. 如果符号加载正确，当执行到断点时，Android Studio会暂停，你可以查看调用栈、变量值等。

这个过程配置较为复杂，需要确保NDK版本、编译标志（-g生成调试信息）等设置正确。但对于解决复杂的逻辑错误和崩溃问题，它是无可替代的。

6. 常见问题排查与实战避坑记录

即使按照教程一步步操作，你也可能会遇到各种问题。下面是我在多年实践中总结的“错误大全”和解决方案。

6.1 编译与链接阶段问题

问题1：System.loadLibrary崩溃，错误信息包含java.lang.UnsatisfiedLinkError: dlopen failed: library “libNativeCalc.so” not found

• 原因：系统在标准库路径下找不到你的.so文件。
• 排查：
  1. 检查文件位置：确认.so文件在APK中的路径是lib/<abi>/libNativeCalc.so。在Unity中，就是放在Assets/Plugins/Android/libs/<abi>/下。
  2. 检查ABI兼容性：你的设备CPU架构（如arm64-v8a）是否在打包的APK中？检查Player Settings中的Target Architectures，确保勾选了对应的ABI。或者检查Assets/Plugins/Android目录下是否有对应ABI的子文件夹。
  3. 检查库依赖：你的.so文件是否依赖其他第三方.so？如果有，它们也需要一并打包进去，并且加载顺序可能有要求（先加载被依赖的库）。可以使用readelf -d libNativeCalc.so | grep NEEDED(Linux) 或dumpbin /DEPENDENTS libNativeCalc.so(Windows) 查看依赖。

问题2：System.loadLibrary崩溃，错误信息包含java.lang.UnsatisfiedLinkError: No implementation found for int com...NativeBridge.addNumbers(...)

• 原因：JNI在.so文件中找不到与Java native方法签名匹配的C++函数。
• 排查：
  1. 检查函数名：使用nm -D libNativeCalc.so(Linux/macOS) 或dumpbin /EXPORTS libNativeCalc.so(Windows) 查看导出的函数名。确认导出的函数名是否与预期的Java_com_yourcompany_yourapp_NativeBridge_addNumbers完全一致（包括大小写和包名中的下划线）。
  2. 检查extern “C”：确保C++实现函数被包裹在extern “C”块中，防止名称修饰。
  3. 检查方法签名：JNI方法签名必须严格匹配。可以使用javac -h . NativeBridge.java命令自动生成包含正确函数原型的头文件，与你实现的cpp文件进行对比。

6.2 运行时崩溃与稳定性问题

问题3：应用运行一段时间后随机崩溃，Logcat中出现signal 11 (SIGSEGV)或signal 7 (SIGBUS)

• 原因：这是典型的“段错误”，通常是C++代码访问了非法内存（空指针、野指针、数组越界、使用已释放内存）或栈溢出。
• 排查：
  1. 启用AddressSanitizer：在CMakeLists.txt中添加编译选项-fsanitize=address -fno-omit-frame-pointer，并链接相应的库。这能在运行时检测出大部分内存错误，并给出详细的错误报告。这是调试Native崩溃的神器。
  2. 检查JNI引用：是否在C++中缓存了JNIEnv*指针并在其他线程使用？JNIEnv*是线程相关的，不能跨线程使用。需要使用JavaVM的AttachCurrentThread来获取当前线程的JNIEnv。
  3. 检查数组访问：所有通过Get<Type>ArrayElements获取的指针，在使用前检查是否为nullptr。确保索引没有越界。
  4. 检查字符串操作：使用GetStringUTFChars获取的字符串，使用后必须用ReleaseStringUTFChars释放。

问题4：从C++回调Unity的UnitySendMessage时，Unity收不到消息或收不到正确消息

• 原因：
  1. GameObject名称或方法名错误：UnitySendMessage的第一个参数是GameObject的名称，第二个参数是脚本上的方法名。两者必须完全匹配，包括大小写。确保场景中存在该名称的GameObject，并且该GameObject上挂载的脚本包含一个public void OnNativeMessage(string msg)方法。
  2. 线程问题：如果回调是从C++的工作线程（非Unity主线程）发起的，直接调用JNI函数访问Unity对象可能不安全。UnitySendMessage本身是线程安全的，但它内部的机制会将消息派发到主线程执行。然而，如果你在回调中做了其他复杂的JNI操作，可能需要考虑线程同步。
  3. 字符串编码：确保传递的字符串是有效的。

6.3 打包与发布问题

问题5：在Editor中运行正常，打Release包后调用Native方法崩溃

• 原因：Release构建通常会进行代码优化（如内联、删除未使用函数），并剥离调试符号。这可能导致一些问题。
• 排查：
  1. 检查代码剥离：Unity的Managed Stripping Level（在Player Settings > Publishing Settings > Minify）如果设置过高（如High），可能会错误地移除用于反射调用Java方法的代码。尝试将其设置为Low或Disabled进行测试。
  2. 检查ProGuard/R8：如果你启用了ProGuard（现在默认是R8），它可能会混淆或移除你的Java桥梁类NativeBridge。你需要在proguard-user.txt或自定义的ProGuard规则文件中添加保留规则：

     -keep class com.yourcompany.yourapp.NativeBridge { *; }

  3. 检查NDK编译优化：某些激进的编译器优化（如-O3）可能会引入难以预料的bug。可以尝试在CMake中为Release模式使用-O2而不是-O3。

问题6：APK体积过大，发现包含了很多未使用的ABI的.so文件

• 解决方案：
  1. 使用Android App Bundle (.aab)：这是Google Play官方推荐的发布格式。你上传一个.aab文件，Google Play会针对用户设备的ABI动态生成最优的APK，只包含所需的.so文件。
  2. 在Unity中分ABI打包：在Player Settings的Target Architectures中，只勾选你真正需要支持的ABI。例如，如果只支持现代设备，可以只勾选ARM64。这能显著减小APK体积。
  3. 使用APK拆分：可以配置Gradle构建脚本，为每个ABI生成单独的APK。

踩过这些坑之后，我的核心建议是：建立稳定的调试流程。从最简单的整数加法开始，确保链路通。然后逐步增加复杂度（传字符串、传数组、多线程回调）。每增加一个功能，就在真机上充分测试。善用Logcat和AddressSanitizer，它们能帮你定位90%以上的Native层问题。最后，在项目早期就确定好NDK版本、ABI支持策略和发布流程，并形成文档，这对团队协作至关重要。