簡介一份面向Unity開發(fā)者的原生安卓調(diào)用入門工具集圍繞UnityActivity、UnityAppContext、PackageManager、RunOnUIThread等核心方法覆蓋Toast、Log、Java與C#字符串互轉等基礎交互并整合網(wǎng)上常用方式與自制封裝提供獲取App列表、判斷服務/應用運行狀態(tài)、打開/安裝/卸載App、發(fā)送廣播以及獲取WiFi狀態(tài)、安卓版本、原生類型ID、內(nèi)置SD卡路徑等系統(tǒng)信息。壓縮包共45個文件以cs腳本、asset場景資源、meta配置文件為主另有unity場景、xml配置、txt說明和jar包整體僅48KB結構清晰便于按需取用。目前已有743人學習瀏覽。借助該工具集可減少原生插件開發(fā)的前期摸索直接復用現(xiàn)成方法快速集成到自己的Unity項目中同時可作為入門參考理解Unity與安卓原生交互的常見調(diào)用方式與封裝思路。1. Unity調(diào)用原生安卓這件事值得先搞清邊界再動手很多開發(fā)者第一次在 Unity 里遇到需要調(diào)用安卓原生能力時想的都是趕緊搜一段 AndroidJavaClass(android.widget.Toast) 的示例代碼貼上去。某開發(fā)者在做一個跨平臺工具時也這么干過結果項目能編譯通過真機上一跑就崩最終發(fā)現(xiàn)是 Activity 引用為 null。Unity 調(diào)用原生安卓不是一句用 AndroidJavaClass 就行那么輕巧它涉及 JNI 橋接、Activity 生命周期、構建產(chǎn)物aar/jar如何進入最終 APK 等一系列前提。這份工具集適合已經(jīng)在 Unity 里做過基礎功能、卻卡在原生互通這一步的從業(yè)者它能幫你快速搭出可運行的調(diào)用鏈路也把最容易踩的坑預先標出來。2. 橋接原理與工程準備JNI 鏈路和三個前置配置2.1 Unity 與安卓之間那層 JNIAndroidJavaClass 到底做了什么Unity 在安卓側不是簡單地反射調(diào)用。每個 AndroidJavaClass / AndroidJavaObject 實例背后都對應一個 JNI 全局引用。JNI 是 Java 與 C/C 之間的橋梁而 Unity 的 C# 層通過一組內(nèi)部封裝的 JNI 接口把類型信息、方法簽名、參數(shù)值一層層傳到 Java 虛擬機里。當一個 C# 腳本寫下AndroidJavaClass jc new AndroidJavaClass(com.unity3d.player.UnityPlayer); AndroidJavaObject activity jc.GetStaticAndroidJavaObject(currentActivity);這里實際發(fā)生了兩件事第一JNI 層根據(jù)類名com.unity3d.player.UnityPlayer去已加載的類里查找第二讀取靜態(tài)字段 currentActivity 并返回一個 JNI 引用。這個引用在 C# 側被包裝成 AndroidJavaObject底層指針指向 Java 堆上的 Activity 實例。理解這一點很重要如果你持有這個引用而 Activity 已經(jīng)被系統(tǒng)回收那后續(xù)任何 Call 都可能拋異常。從調(diào)用模型上看Unity 側所有對 Java 的調(diào)用都是單向、同步的除非你主動開線程。也就是說C# 調(diào)用 Java 方法后線程會卡在 JNI 調(diào)用點上直到 Java 方法返回。這給后續(xù)的性能優(yōu)化留下了一個課題第5章會專門講。2.2 工程側三個前置配置SDK、Player Settings 和 Plugins/Android 目錄在我經(jīng)手的幾個 Unity安卓互通項目里大部分跑不通的第一原因不是代碼寫錯而是工程配置不完整。需要先整理好三件事。第一Android SDK 路徑。Unity 的 Preferences 里 External Tools 面板需要正確指向 SDK 位置。如果你同時裝了 Android StudioSDK 路徑一般在 Android/Sdk 目錄。如果路徑不對Unity 打包時會直接報SDK not found這個一般難不倒人。第二Player Settings。打開 Edit Project Settings Player切換到 Android 標簽頁。重點檢查三項Package Name包名必須與之后 Android 工程里要合并的 manifest 包名兼容避免沖突。Minimum API LevelUnity 會以此為準來決定哪些 API 可直接調(diào)用。設置太低Java 側一些新接口會因 NoSuchMethodError 掛掉設置太高又會壓縮可覆蓋的機型范圍。Scripting BackendIL2CPP 和 Mono 在跨語言調(diào)用上的行為其實不一樣。IL2CPP 對 AOT 的限制更嚴格如果后續(xù)要在 IL2CPP 下做裁剪strip engine code某些反射調(diào)用會被裁掉需要加 link.xml。這點容易被忽略后面避坑章節(jié)會有一個專門案例。第三Plugins/Android 目錄。Unity 在構建 APK/AAB 時會把這個目錄下的內(nèi)容合并進最終工程。最常見的路徑是 Assets/Plugins/Android。要注意的是這個目錄里如果同時存在同名不同版本的文件比如兩個版本的 support 庫最終行為完全取決于 Unity 內(nèi)部的合并順序這在后面也會細說。2.3 最小調(diào)用鏈路從 Unity 發(fā)一條 Toast 驗證通路工程配置完成后先別急著寫業(yè)務代碼。我用一條最簡單的 Toast 驗證整條通路。創(chuàng)建一個 C# 腳本掛在場景主物體上using UnityEngine; public class NativeBridge : MonoBehaviour { void Start() { ShowToast(Hello from Unity); } public void ShowToast(string msg) { AndroidJavaClass unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer); AndroidJavaObject currentActivity unityPlayer.GetStaticAndroidJavaObject(currentActivity); AndroidJavaClass toastClass new AndroidJavaClass(android.widget.Toast); // 最后一個參數(shù) 0 表示 LENGTH_SHORT1 表示 LENGTH_LONG AndroidJavaObject toast toastClass.CallStaticAndroidJavaObject(makeText, currentActivity, msg, 0); toast.Call(show); } }這里解釋一下關鍵點com.unity3d.player.UnityPlayer 是 Unity 在安卓側的核心類currentActivity 這個靜態(tài)字段在任何標準 Unity Activity 生命周期內(nèi)都可訪問。makeText 是 Toast 的靜態(tài)方法接收三個參數(shù)Context、CharSequence、duration。C# 傳字符串、int 時JNI 層會自動映射到對應的 Java 類型。toast.Call(show) 調(diào)用的是實例方法返回值是 void所以直接 Call 即可。代碼是通了但有個細節(jié)必須說不要在任何回調(diào)、協(xié)程恢復、或者事件系統(tǒng)里反復 new AndroidJavaClass。這是因為每 new 一次JNI 全局引用表里就會多一條引用長期運行可能把引用表撐爆。這個坑很隱蔽實際項目里遇到過一次排查了一整天才定位到。3. 三種集成方式與參數(shù)透傳從反射調(diào)用到導出 aar3.1 方式一運行時反射——適合輕量調(diào)用不碰 Android Studio如果你只是調(diào)用系統(tǒng) APIToast、振動、剪貼板或者調(diào)用一個不常改動的第三方 Java 靜態(tài)方法運行時反射方式最省事。它不需要你在 Android Studio 里建工程也不需要導出 aar直接把類名、方法名、參數(shù)寫在 C# 里。比如讀取設備 Android IDpublic string GetAndroidId() { AndroidJavaClass unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer); AndroidJavaObject activity unityPlayer.GetStaticAndroidJavaObject(currentActivity); AndroidJavaObject resolver activity.CallAndroidJavaObject(getContentResolver); AndroidJavaClass settingsSecure new AndroidJavaClass(android.provider.Settings$Secure); // 第二個參數(shù)是默認值當系統(tǒng)未開啟時返回的兜底字符串 string androidId settingsSecure.CallStaticstring(getString, resolver, android_id); return androidId; }這種方式的好處是靈活C# 改完直接跑。壞處也明顯沒有任何編譯期檢查方法名拼錯、參數(shù)類型傳錯都得運行時報異常而且異常信息被 JNI 層包了一層Logcat 里往往是 UnsatisfiedLinkError 或 NoSuchMethodError對新人來說排查成本高。所以我一般會在方法入口包一層 try-catch把異常信息帶出來try { // ... 調(diào)用邏輯 } catch (System.Exception e) { Debug.LogError($[NativeBridge] JNI 調(diào)用失敗: {e.Message}); }這樣至少能看到是類找不到、方法找不到還是參數(shù)類型不匹配。3.2 方式二導出 aar——功能復雜時更穩(wěn)的工程化路徑當你的原生代碼里開始有多個類、有 Activity 跳轉、有回調(diào)接口的時候運行時反射方式會變得很脆每改一次 Java 代碼都要重新打包、替換文件。這個階段就要轉到 Android Library 工程上去。常見做法是在 Android Studio 里新建一個 Library Module然后編寫原生邏輯。我用一個最小示例模塊名比如叫 nativebridgepackage com.example.nativebridge; import android.content.Context; import android.widget.Toast; public class Bridge { private Context context; public Bridge(Context ctx) { this.context ctx.getApplicationContext(); } public void show(String message) { Toast.makeText(context, message, Toast.LENGTH_SHORT).show(); } public int add(int a, int b) { return a b; } }模塊的 build.gradle 需要做兩處關鍵配置android { defaultConfig { // 這兩項必須和 Unity 的 Player Settings 匹配或更低 minSdkVersion 22 targetSdkVersion 34 } }導出的 aar 文件位置一般在 build/outputs/aar/ 下。把這個 aar 復制到 Unity 工程的 Assets/Plugins/Android 目錄后在 C# 側這樣調(diào)用public class NativeBridge : MonoBehaviour { private AndroidJavaObject bridgeObj; void Start() { AndroidJavaClass unityPlayer new AndroidJavaClass(com.unity3d.player.UnityPlayer); AndroidJavaObject activity unityPlayer.GetStaticAndroidJavaObject(currentActivity); // 構造 Bridge 實例傳入當前 Activity 的 ApplicationContext bridgeObj new AndroidJavaObject(com.example.nativebridge.Bridge, activity); bridgeObj.Call(show, bridge ready); int sum bridgeObj.Callint(add, 3, 5); Debug.Log([NativeBridge] sum sum); } void OnDestroy() { // 顯式釋放 JNI 引用長期項目尤其重要 bridgeObj?.Dispose(); } }這段代碼里有兩個值得說的點。第一new AndroidJavaObject(com.example.nativebridge.Bridge, activity) 的第二個參數(shù)會被 JNI 當作構造函數(shù)的第一個參數(shù)。因為 Bridge 的構造器接收 Context這里傳 activity 正好匹配。如果構造函數(shù)是重載的JNI 會根據(jù)傳入?yún)?shù)類型去匹配簽名匹配不到會拋 NoSuchMethodError。第二OnDestroy 里做 Dispose。不看 GC 的情況下C# 側的 AndroidJavaObject 回收是不確定的顯式 Dispose 能防止 JNI 引用表泄漏。3.3 數(shù)據(jù)類型映射表與帶參調(diào)用示例跨語言調(diào)用最容易出錯的是類型映射。下表是我從項目里總結出來的一份常用映射按C# - Java方向C# 側類型Java 側接收類型說明stringString自動轉換為 UTF-16 序列注意不要傳 nullintint32 位整型longlong64 位整型被 JNI 當作 jlongfloatfloat32 位浮點doubledouble64 位浮點boolbooleanJNI 層用 z 表示AndroidJavaObject任意對象傳遞的是 JNI 引用不是拷貝有一個隱蔽的坑C# 的 string 在傳給 Java 時如果值是 nullJNI 層有時候會拋 NullPointerException 而不是友好提示。我在給某個功能傳剪切板文案時翻過一次車文案是空的Java 側收到的直接是 NPE。從那以后所有跨層字符串參數(shù)我都會先做空串兜底。再看一個帶數(shù)組參數(shù)的例子。假設 Java 側有一個方法接收 int[] 和 String[]public void processArray(int[] values, String[] names) { // 業(yè)務邏輯 }C# 側調(diào)用路徑是int[] values { 10, 20, 30 }; string[] names { alpha, beta }; bridgeObj.Call(processArray, values, names);注意這里不能傳 List 或 List JNI 不會幫你做集合到數(shù)組的轉換。你需要手動轉一次Liststring nameList new Liststring { alpha, beta }; bridgeObj.Call(processArray, values, nameList.ToArray());3.4 從安卓側拿返回值同步調(diào)用與異常捕獲前面 add 的例子已經(jīng)展示了 Call 同步拿返回值。這里的同步要再次強調(diào)Unity 的調(diào)用線程會阻塞直到 Java 方法執(zhí)行完。如果 Java 方法里有耗時操作比如網(wǎng)絡請求Unity 的 Update 循環(huán)會卡住表現(xiàn)就是游戲畫面掉幀甚至看起來像卡死。情況再極端一點如果 Java 方法內(nèi)部真正做的是阻塞在主線程上的東西而 Unity 側恰好是在主線程調(diào)用那連 Activity 的 UI 事件都處理不了最終可能觸發(fā) ANR。處理方式是讓 Java 側把耗時操作放到子線程或者 C# 側用異步包裝。C# 側異步包裝的一個簡單方式是用協(xié)程輪詢結果。Java 側先啟動任務C# 側每幀檢查一個是否完成的標記IEnumerator WaitForNativeResult() { bool done bridgeObj.Callbool(isTaskDone); while (!done) { yield return null; done bridgeObj.Callbool(isTaskDone); } string result bridgeObj.Callstring(getResult); Debug.Log([NativeBridge] async result: result); }這段輪詢代碼適合低頻任務但如果每幀檢查頻繁JNI 調(diào)用開銷會累積。更高效的做法是讓 Java 側在任務完成時主動回調(diào) Unity這個到第5章展開。4. 高頻踩坑與排查五個典型問題的現(xiàn)象和根因這一章是我實際調(diào)試中遇到最多的問題。每條都按現(xiàn)象 - 原因 - 解決來寫讀的時候可以對照自己的項目逐條排除。4.1 現(xiàn)象調(diào)用 Java 方法直接閃退Logcat 提示 currentActivity 為 null原因UnityPlayer 的 currentActivity 靜態(tài)字段會在 Activity 的早期生命周期階段未被賦值。如果調(diào)用發(fā)生在 Application.onCreate比如你在自定義 Application 里初始化 SDK或者發(fā)生在 Activity.onDestroy 之后那拿到的引用就是 null。JNI 把 null 傳給 Java 方法時很多原生方法會直接拋空指針。解決把初始化時機推遲到第一個場景加載完成后或者緩存當前 activity 之后手動判空if (currentActivity null) { Debug.LogError([NativeBridge] currentActivity 為空檢查調(diào)用時機); return; }另外如果你的項目里啟用了自定義的 Intent Filter 或者使用了別的安卓組件currentActivity 在不同進程里可能不一致這時候不要依賴它做操作改成傳 Application Context 更穩(wěn)。4.2 現(xiàn)象aar 文件放在 Assets/Plugins/Android 下打包出來類找不到原因這類問題我遇到三種情況。第一aar 里的 AndroidManifest.xml 與 Unity 主工程 manifest 沖突導致整個 aar 沒有被打進最終包第二aar 的 minSdkVersion 高過 Unity 項目的 Minimum API LevelGradle 合并時直接跳過第三Unity 版本太老2019 之前對 aar 原生產(chǎn)物的支持有缺陷需要改成導出 Project 再通過 Android Studio 集成。解決先檢查 aar 是否存在用壓縮工具打開確認里面 classes.jar 是否包含你的類。再在 Player Settings 里調(diào)高 Minimum API Level 到至少和 aar 持平。如果還不行用 Unity 的 Export Project 導出 Gradle 工程然后在 Android Studio 里手動添加 aar 依賴看 Android Studio 的 Gradle 面板輸出會更明確。4.3 現(xiàn)象從 Java 子線程調(diào)用 UnitySendMessageUnity 側偶爾收到、偶爾崩潰原因UnitySendMessage 這個接口在部分版本下要求必須從 Unity 主線程GL 線程調(diào)用。Java 子線程直接調(diào)時如果正好趕上 Unity 渲染管線切換會觸發(fā)一個未定義行為表現(xiàn)就是時好時壞。解決Java 側不要在子線程直接調(diào)而是先用 Handler 把回調(diào) post 到主線程再在主線程里調(diào)用 UnitySendMessageHandler mainHandler new Handler(Looper.getMainLooper()); mainHandler.post(new Runnable() { Override public void run() { UnityPlayer.UnitySendMessage(BridgeObject, OnNativeResult, done); } });這段代碼把真正調(diào)用 UnitySendMessage 的時機鎖定在安卓主線程規(guī)避了跨線程同步問題。4.4 現(xiàn)象C# 傳 longJava 方法簽名是 int方法能調(diào)到但參數(shù)值不對原因JNI 的參數(shù)匹配是按照方法簽名嚴格來的C# 的 long 會映射成 Java 的 long而 Java 的 int 需要的是 C# 的 int兩者簽名的類型描述符不同本來應該拋 NoSuchMethodError。但某些 API特別是系統(tǒng) API可能有重載JNI 匹配到了另一個重載參數(shù)被靜默截斷。表現(xiàn)就是代碼能跑結果錯得離譜。解決嚴格按第3章的映射表來。不確定 Java 方法簽名時用 javap -s 查看真實簽名然后回到 C# 側比對。再補充一條這個方法在編譯時不會報錯因為 AndroidJavaObject.Call 的泛型參數(shù)只決定了返回值的轉換不決定參數(shù)匹配。很多人在這一步翻車最后只能用日志排查。4.5 現(xiàn)象Release 構建在真機上跑報 NoClassDefFoundErrorDebug 構建正常原因這是混淆或裁剪把類丟了。兩個方向R8/ProGuard 把 Java 側類名混淆了Unity 側再用反射查找原始類名自然找不到另一個是 IL2CPP 的 Managed DLL 裁剪把 Unity 側調(diào)用 JNI 的 C# 類裁掉了Unity 側代碼直接不存在。解決如果是 Android 側混淆在 proguard-rules.pro 里加保留規(guī)則-keep class com.example.nativebridge.** { *; }如果是 IL2CPP 裁剪在 Unity 里添加 link.xml保留包含 JNI 調(diào)用的程序集linker assembly fullnameAssembly-CSharp type fullnameNativeBridge preserveall / /assembly /linker這兩種處理方式在很多項目里是同時要做的缺一不可。5. 進階把回調(diào)鏈路理順再做一次 JNI 調(diào)用瘦身5.1 用 UnitySendMessage 做雙向通信的完整閉環(huán)前面提到 Java 側要主動通知 Unity 時用 UnitySendMessage。雙向通信在業(yè)務上往往是這樣閉環(huán)的Unity 發(fā)起一個請求Java 側在后臺執(zhí)行完成后回傳結果。Java 側關鍵代碼public void startAsyncWork(final String param) { new Thread(new Runnable() { Override public void run() { // 模擬耗時 String result process(param); // 回調(diào)到 Unity 側 runOnMainThread(new Runnable() { Override public void run() { UnityPlayer.UnitySendMessage(BridgeObject, OnNativeResult, result); } }); } }).start(); }Unity 側對應接收方法public class BridgeObject : MonoBehaviour { void OnNativeResult(string json) { // 這里天然在主線程可以直接操作 Unity API ResultData data JsonUtility.FromJsonResultData(json); Debug.Log([NativeBridge] data.code data.message); } }注意 UnitySendMessage 的第一個參數(shù)是場景里的 GameObject 名稱第二個是掛在它上面的組件里的方法名。GO 沒找到或者方法名不存在時Unity 只在 Logcat 里打一條 warning不會崩潰這也會讓問題更難發(fā)現(xiàn)。我的習慣是在 Start 里顯式檢查一次if (FindObjectOfTypeBridgeObject() null) { Debug.LogError([NativeBridge] BridgeObject 不存在回調(diào)會靜默丟失); }5.2 高頻調(diào)用場景下的引用緩存與批量透傳最后一個貼士關于性能。高頻調(diào)用時別每幀 new AndroidJavaClass。把類引用和實例引用緩存起來即可private static AndroidJavaClass sBridgeClass; private static AndroidJavaObject sBridgeObj; public static AndroidJavaObject GetBridge() { if (sBridgeObj null) { sBridgeClass new AndroidJavaClass(com.example.nativebridge.Bridge); // 初始化實例只做一次 } return sBridgeObj; }至于批量透傳把多個參數(shù)拼成 JSON 字符串給 Java 側解析可以把多次 JNI 調(diào)用合并成一次。我在某個模擬項目 X 里實踐過用 dispatch(json) 統(tǒng)一入口后原來每幀 20 次 JNI 調(diào)用降到 1 次。JNI 單次調(diào)用成本在微秒級一幀幾十次就會明顯吃掉主線程時間。從那個第一次跑 Toast 就閃退的項目到現(xiàn)在我每次接安卓原生功能都強制先走一遍最小鏈路驗證再談業(yè)務擴展。閾值設得很簡單Toast 能彈出來通路就通了通路不通后面所有功能都等于白搭。這個習慣幫我省下過很多個下午。希望幫到你。本文還有配套的精品資源點擊獲取