從寫 Rust 代碼到真正把 .so 塞進(jìn) Android、把 xcframework 塞進(jìn) iOS中間隔著一整條工具鏈、鏈接器、ABI 和打包規(guī)范的鴻溝。這堂課我把雙端集成的完整路徑梳理了一遍Android 端從 jni 接口到 AAR 打包iOS 端從 C FFI 到 xcframework 生成最后講清楚我在兩端聯(lián)調(diào)時踩過的那些坑。如果你正在做 AI 推理、數(shù)據(jù)預(yù)處理或者任何需要 Rust 高性能模塊的移動端交付這篇可以直接照著走。先說結(jié)論Rust 寫業(yè)務(wù)邏輯只是第一步真正的工程量在“跨語言邊界”和“出包產(chǎn)物”上。Android 要的是 AAR 里裹著 jniLibs/*.soiOS 要的是 xcframework 里躺著不同架構(gòu)的靜態(tài)庫或動態(tài)庫兩端各有一套 ABI 體系但 Rust 源碼可以完全共用。這就是這門課的核心邏輯——用 Rust 的統(tǒng)一實(shí)現(xiàn)換雙端一致的運(yùn)行行為省掉兩套原生代碼的重復(fù)開發(fā)和維護(hù)。1. 項目整體設(shè)計與雙端底層邏輯拆解1.1 為什么 AI 模塊用 Rust而不是 Kotlin/Java 或 Swift/ObjC我的場景是這樣的底層的 tokenizer 和 embedding 計算用 C 寫了一版效果沒問題但跨端維護(hù)成本太高。Android 端 JNI 調(diào) C、iOS 端 bridge 調(diào) C兩邊簽名靠手寫頭文件維護(hù)AI 模型和推理 runtime 升級一次就要兩端同步改一輪。后來把核心模塊用 Rust 重寫之后整個交付邏輯清晰了很多。Rust 在 AI 模塊里的核心優(yōu)勢用大白話講有三點(diǎn)第一是內(nèi)存安全與計算性能能同時拿到。AI 推理里大量高頻的向量運(yùn)算、矩陣乘、字符串編碼C 做起來要小心越界和懸垂指針Rust 在保證內(nèi)存安全的條件下做了零成本抽象循環(huán)展開、SIMD 優(yōu)化這些都能直接享受。用criterion做基準(zhǔn)測試同樣的 tokenizer 邏輯Rust 版本和 C 版本性能在同一量級但我?guī)缀醪挥迷倩〞r間追內(nèi)存泄漏。第二是跨平臺能力。Rust 通過 target triple 支持 Androidaarch64-linux-android/armv7-linux-androideabi和 iOSaarch64-apple-ios/x86_64-apple-ios/aarch64-apple-ios-sim一份源碼各自編譯成對應(yīng)平臺的二進(jìn)制。這跟 Kotlin Multiplatform 的思路不一樣——Rust 不提供業(yè)務(wù)框架而是提供一個“可以用 FFI 調(diào)用的高性能計算內(nèi)核”。第三是二進(jìn)制體積和啟動性能可控。Rust 的 release 構(gòu)建經(jīng)過opt-levelz和ltotrue優(yōu)化后一個獨(dú)立的 .so 或 .a 往往只有幾百 KB 到幾 MB。移動端對包體積很敏感AI 模塊做小留給模型文件的空間就更大。這選的代價是調(diào)用雙方必須通過 FFI 邊界字符串、數(shù)組、回調(diào)都要做一層序列化和指針轉(zhuǎn)換。我的目標(biāo)就是把這一層做得足夠薄讓 AI 模塊內(nèi)部可以專注計算邏輯而把 Java/Kotlin 和 Swift 的類型系統(tǒng)“翻譯”工作收斂在接口層。1.2 兩端交付形態(tài)的核心差異JNI 動態(tài)鏈路 vs C FFI 靜態(tài)鏈路Android 和 iOS 雖然都是用 C ABI 作為 Rust 和其他語言之間的“通用語言”但工程形態(tài)完全不同。Android 用的 JNIJava Native Interface。Rust 編譯產(chǎn)物是.so動態(tài)庫JVM 通過System.loadLibrary(xxx)在運(yùn)行時加載它。JNI 要求函數(shù)名必須按照規(guī)范簽名比如Java_com_example_MyClass_nativeMethod還要處理 JNIEnv 指針、jobject 引用這些東西。這套機(jī)制足夠靈活但動態(tài)庫的初始化時機(jī)、不同 ABI 目錄arm64-v8a、armeabi-v7a、x86_64的兼容性都要在出包時謹(jǐn)慎處理。iOS 走的是標(biāo)準(zhǔn) C 符號鏈接。如果 Rust 編成.a靜態(tài)庫鏈接進(jìn) App 可執(zhí)行文件里就不涉及運(yùn)行時動態(tài)加載如果編成.dylib還要處理簽名和 embed 的問題。實(shí)踐上首選靜態(tài)庫配合 xcframework 把模擬器和真機(jī)切片打包在一起Xcode 在編譯時自動挑合適的架構(gòu)。表格對比更直觀維度AndroidiOSRust 產(chǎn)物.so 動態(tài)庫.a 靜態(tài)庫推薦語言邊界機(jī)制JNIC FFI / ObjC bridge架構(gòu)切片arm64-v8a 等device simulator集成產(chǎn)物AARxcframework調(diào)用方式loadLibrary JNI 簽名Header 聲明 鏈接符號理解了這兩條鏈路后面每一步操作都是順著這條主線“填空”。2. JNI 接口層設(shè)計與跨語言數(shù)據(jù)傳遞2.1 接口層該暴露什么、藏什么一個 AI 推理模塊的接口設(shè)計我接手的項目里Rust 核心模塊承擔(dān)了三個職責(zé)加載 tokenizer 詞表、字符串編碼成 token IDs、調(diào)用 ONNX runtime 做推理。Android/iOS 上層需要拿到的是 int 數(shù)組token IDs、String解碼結(jié)果以及狀態(tài)碼成功/失敗。我的設(shè)計原則是“一個公開函數(shù)只干一件大事返回值盡量是簡單類型”。拿 tokenizer 舉例Java 層需要的就是String[] tokenize(String text)或者更高效的int[] tokenize(String text)——把字符串轉(zhuǎn)換成一組 id。在 JNI 層我不會直接返回 Java 對象而是返回一個jlong指針指向 Rust 側(cè)一個常量字符串?dāng)?shù)組或字節(jié)數(shù)組然后由 JNI 封裝層把它轉(zhuǎn)換成 Java 數(shù)組。為什么這么做跨語言邊界最怕的就是對象生命周期管理Java 持有 Rust 分配的內(nèi)存如果不主動釋放就是泄漏讓 JNI 層每次調(diào)用時把數(shù)據(jù)拷貝到 Java 數(shù)組內(nèi)存所有權(quán)還是歸 Rust 管一次性釋放簡單可靠。下面是 rust 側(cè)核心接口的骨架use jni::objects::{JClass, JString}; use jni::sys::{jbyteArray, jintArray, jlong}; use jni::JNIEnv; #[no_mangle] pub extern system fn Java_com_example_ai_MyRustLib_tokenize( env: JNIEnv, _class: JClass, input: JString, ) - jintArray { let input_str: String env .get_string(input) .expect(couldnt get java string) .into(); let tokens my_core::tokenize(input_str); // 拷貝結(jié)果到 jintArray let len tokens.len() as i32; let array env.new_int_array(len).expect(couldnt create int array); env.set_int_array_region(array, 0, tokens) .expect(couldnt set array region); array }這個函數(shù)表面上是 tokenize但它在 ABI 層面的真實(shí)身份是 JNI 入口參數(shù)里帶著 JNIEnv 指針。這里的extern system很關(guān)鍵它保證符號按 C 調(diào)用約定導(dǎo)出而不是 Rust 的加殼約定。Java 層調(diào)用時傳入一個 String拿到一個 int[]整個過程走的是 JNI 的 GetStringUTFChars / NewIntArray 的底層機(jī)制但 Rust 側(cè)封裝好了不需要手動碰 C 字符串指針。2.2 從 Rust 返回字符串、數(shù)組和錯誤碼時容易忽略的細(xì)節(jié)字符串跨語言傳遞是我踩過最多坑的地方。JNI 的get_string拿到的是JString轉(zhuǎn)成 Rust String 是拷貝操作這個開銷在 tokenize 這種高頻函數(shù)上積少成多。等成本優(yōu)化后我會在接口層做一個緩沖復(fù)用如果輸入長度在某個范圍內(nèi)直接復(fù)用 JNI 側(cè)的一塊固定緩沖區(qū)減少 JNI 調(diào)用的分配次數(shù)。返回字符串時我習(xí)慣返回jstring而不是*const c_char。原因很簡單Java 層原生處理 String 最方便JNI 的env.new_string()可以直接包裝 Rust 字符串。但是要注意new_string接收的是 JNI 的修改過的 UTF-8 字符串碰到超長字符串和特殊字符時要謹(jǐn)慎盡量先用 Java 側(cè)做編碼轉(zhuǎn)換保證數(shù)據(jù)一致。錯誤碼統(tǒng)一用整數(shù)0 表示成功負(fù)數(shù)表示不同的錯誤類型。比如 tokenizer 加載失敗返回 -1模型推理超時返回 -2參數(shù)錯誤返回 -3。Java 層和 Swift 層各自寫一個枚舉映射不需要跨語言拋異?！缯Z言拋異常這件事在 JNI 里很難處理干凈在 Swift 側(cè)更麻煩。#[no_mangle] pub extern system fn Java_com_example_ai_MyRustLib_getStatus( env: JNIEnv, _class: JClass, ) - jint { my_core::engine_status() as i32 }此外Rust 的 panic 默認(rèn)會 unwinding越過了 FFI 邊界是未定義行為這在移動端是致命的。一定要在入口函數(shù)里設(shè)置 panic 捕獲#[no_mangle] pub extern system fn Java_com_example_ai_MyRustLib_tokenize(...) - jintArray { std::panic::catch_unwind(|| { // 原有邏輯 }) .unwrap_or_else(|_| { // 返回空數(shù)組或錯誤碼 }) }這一條幾乎所有的入門教程都沒講但缺了它生產(chǎn)環(huán)境的崩潰率直接上升一個量級。2.3 iOS 側(cè) C FFI 橋接的接口對稱性iOS 側(cè)沒有 JNI 那套東西接口層要薄很多。我直接在 Rust 里導(dǎo)出一組 C 函數(shù)#[no_mangle] pub extern C fn tokenizer_load_model(path: *const c_char) - i32 { ... } #[no_mangle] pub extern C fn tokenizer_encode(text: *const c_char, out_ids: *mut i64, max_len: i32) - i32 { ... } #[no_mangle] pub extern C fn tokenizer_free() { ... }Rust 側(cè)把*const c_char轉(zhuǎn)成str時會檢查空指針和 UTF-8 合法性靠std::ffi::CStr。輸出參數(shù)out_ids指向的緩沖區(qū)由 Swift 側(cè)分配Rust 只往里寫不負(fù)責(zé)釋放避免所有碰內(nèi)存所有權(quán)的問題。Swift 側(cè)用_cdecl或者直接 import 頭文件來聲明這些函數(shù)然后在Tokenizer.swift里封裝一下把 C 指針操作收斂到一個文件里上層業(yè)務(wù)完全不感知 C 的存在。這就是對稱性Android 的 JNI 封裝層和 iOS 的 Swift 封裝層雖然在語法上天差地別但設(shè)計模式都是“把 FFI 邊界封裝在一個模塊里上層只面對普通的類型”。3. Android 實(shí)操從 .so 到 AAR 的完整構(gòu)建與集成3.1 rustup 目標(biāo)添加與 .cargo/config.toml 交叉編譯配置在 Android 上編 Rust第一步要給 rustup 添加 Android targetrustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android三個 target 分別對應(yīng) arm64-v8a、armeabi-v7a、x86_64。x86_64 通常只用于模擬器但 CI 里跑測試會用到。這里的關(guān)鍵點(diǎn)是 NDK 工具鏈Rust 在編譯時會調(diào)用 NDK 里的 clang 和鏈接器需要 ndk 路徑。我在項目的.cargo/config.toml里寫死[target.aarch64-linux-android] linker /Users/me/Library/Android/sdk/ndk/25.2.9519653/toolchains/llvm/prebuilt/darwin-x86_64/bin/aarch64-linux-android24-clang [target.armv7-linux-androideabi] linker /Users/me/Library/Android/sdk/ndk/25.2.9519653/toolchains/llvm/prebuilt/darwin-x86_64/bin/armv7a-linux-androideabi24-clang [target.x86_64-linux-android] linker /Users/me/Library/Android/sdk/ndk/25.2.9519653/toolchains/llvm/prebuilt/darwin-x86_64/bin/x86_64-linux-android24-clang路徑里的-android24是 API level28 或 21 都行但要和你 app 的 minSdk 對齊推薦。如果你的 minSdk 是 26最好編一個 26 的 clang避免運(yùn)行時鏈接到不存在的 libc 符號。強(qiáng)烈建議不要手動寫路徑用環(huán)境變量ANDROID_NDK_HOME替代腳本里動態(tài)拼鏈接器路徑否則換個 NDK 版本整個工程就廢了。構(gòu)建命令直接cargo build --release --target aarch64-linux-android生成物在target/aarch64-linux-android/release/libmycore.so。體積控制注意Cargo.toml[profile.release] opt-level z lto true codegen-units 1 panic abort strip debuginfoopt-level z是優(yōu)化體積panic abort還能進(jìn)一步減小體積。這里要注意如果 Rust 側(cè)存在可能 panic 的 FFI 入口panic abort相當(dāng)于讓整個進(jìn)程直接 abort而不走 unwinding。所以我在入口函數(shù)里用catch_unwind把所有邏輯兜住這樣 panic 不會穿過 FFI 邊界進(jìn)程也不會崩最壞情況是錯誤碼歸 -1。3.2 用 cargo-ndk 一鍵產(chǎn)出多 ABI 的 .so如果獨(dú)立項目追求效率直接上cargo-ndkcargo install cargo-ndk cargo ndk -t arm64-v8a -t armeabi-v7a -t x86_64 -o ../android/src/main/jniLibs build --release這個命令會同時生成三種 ABI 的 .so并按 Android 約定的 jniLibs 目錄結(jié)構(gòu)放到指定路徑下android/src/main/jniLibs/ ├── arm64-v8a/ │ └── libmycore.so ├── armeabi-v7a/ │ └── libmycore.so └── x86_64/ └── libmycore.so這種目錄結(jié)構(gòu)可以直接被 Gradle 識別如果項目是純 Android 工程放到 src/main/jniLibs 下就完事了。如果 Rust 是獨(dú)立工作區(qū)把 .so 文件拷貝過去即可。這里有個細(xì)節(jié)lib前綴不能丟。Android 的 System.loadLibrary 會自動補(bǔ)這層前綴但如果你的 .so 文件名不是lib開頭就加載不到。3.3 手動拼 AAR把 jniLibs、manifest 和 ProGuard 規(guī)則塞進(jìn)去如果不想依賴 Android Studio 的 Gradle 插件自動生成 AAR可以手動構(gòu)造。AAR 本質(zhì)上是一個 zip 包但里面要有特定的目錄結(jié)構(gòu)mycore.aar/ ├── AndroidManifest.xml ├── classes.jar ├── jni/ │ ├── arm64-v8a/ │ │ └── libmycore.so │ ├── armeabi-v7a/ │ │ └── libmycore.so │ └── x86_64/ │ └── libmycore.so ├── R.txt └── proguard.txt一個標(biāo)準(zhǔn) AAR 必須有AndroidManifest.xml和classes.jar即使 Manifest 內(nèi)容為空也要存在R.txt也是空的也可能被 Gradle 讀取。手動 zip 時名字必須是.aar。比如我寫了一個MyRustLib.java把它編譯成 classes.jar 塞進(jìn) AAR上層 Module 通過compileOnly或api依賴這個 AAR就能直接調(diào)用MyRustLib.tokenize()。jni 目錄下按 ABI 分文件夾Gradle 在最終打包 APK 時會根據(jù)主 App 的 abiFilters 自動選擇包含哪些 .so。實(shí)際上我通常在項目里直接用 Android Library Module 來管理 Rust 產(chǎn)物而不是手動拼 AAR。流程是新建 Android Library 模塊把 Rust 生成的 jniLibs 放進(jìn)src/main/jniLibs然后在同一個模塊里寫 JNI 封裝類最后 Gradle 的assembleRelease生成 AAR 給上層 App 或其他 Module 使用。3.4 Android Studio 集成abiFilters、minSdk 和 loadLibrary 的坑在上層 App 的 build.gradle 里android { defaultConfig { minSdk 26 ndk { abiFilters arm64-v8a, armeabi-v7a, x86_64 } } }abiFilters的作用是告訴 Gradle 最終 APK 里只保留指定 ABI 的 .so。如果不加Gradle 默認(rèn)會打包所有 ABIAPK 體積變大是一回事更重要的是某些 ABI比如 mips在真實(shí)設(shè)備上根本運(yùn)行不了。加載 .so 的位置也很有講究。JNI 規(guī)范里要求System.loadLibrary在類初始化的時候被調(diào)用比如靜態(tài)代碼塊里public class MyRustLib { static { System.loadLibrary(mycore); } public static native int[] tokenize(String text); }不要放在構(gòu)造函數(shù)里更不要在每次調(diào)用前反復(fù) load。多線程環(huán)境下多個線程同時進(jìn)入 loadLibrary 驅(qū)動會偶發(fā)錯誤。另外一個老坑你的 App 如果引用了其他第三方庫它們內(nèi)部可能也帶 soJNI 庫名沖突會導(dǎo)致加載失敗。另外一個常見問題是 minSdk 與 JNI 函數(shù)簽名無關(guān)但和 .so 的 ELF 版本有關(guān)。如果你編的 so 里面引用了高版本 Android 才有的符號在低版本系統(tǒng)上加載時會報UnsatisfiedLinkError。保持 minSdk 26 以上基本可以避開大多兼容性問題。4. iOS 實(shí)操多架構(gòu)靜態(tài)庫與 xcframework 生成全流程4.1 iOS 平臺架構(gòu)解析真機(jī)、模擬器和 Rosetta 的取舍iOS 的架構(gòu)體系比 Android 簡單但有一個特殊點(diǎn)模擬器。目前的模擬器分兩種Apple Silicon Mac 上跑的是aarch64-apple-ios-simIntel Mac 上跑的是x86_64-apple-ios。第一次用 Rust 編 iOS 庫的人百分之百會在這里迷路——你至少需要三種切片切片對應(yīng)的 target場景真機(jī) ARM64aarch64-apple-iosiPhone/iPad 真機(jī)模擬器 ARM64aarch64-apple-ios-simApple Silicon 上的模擬器模擬器 x86_64x86_64-apple-iosIntel Mac 上的模擬器Apple 已經(jīng)被逼著拋棄 Intel Mac 了但 CI 上可能還有 Intel 的機(jī)器所以 CI 腳本里最好兩種模擬器切片都編上然后用lipo -create或 xcframework 自動處理。添加 targetrustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios編靜態(tài)庫時不需要鏈接器配置因?yàn)?iOS 上 Rust 不產(chǎn)生動態(tài)庫不讓設(shè)置 dylib。如果是編 cdylib 用于測試另說正式集成一律staticlib。在 Cargo.toml 中設(shè)置 crate-type[lib] name mycore crate-type [staticlib, cdylib]編譯時用cargo build --release --target aarch64-apple-ios生成的靜態(tài)庫在target/aarch64-apple-ios/release/libmycore.a。iOS 側(cè)沒有 JNI 那種運(yùn)行時系統(tǒng)調(diào)用約束純靜態(tài)鏈接最省心簽名、權(quán)限、隱私這些完全走 App 的正常流程。4.2 用 xcodebuild 打包 xcframeworkXcode 集成時如何選擇切片早期 iOS 工程都是用 lipo 把多個架構(gòu)合并成一個 fat 庫但 Apple 在 Xcode 12 之后推薦用 xcframework因?yàn)樗苷_表達(dá)每個切片對應(yīng)的平臺和架構(gòu)而不是一個 fat 二進(jìn)制里到處放。xcframework 的生成命令# 先生成三個靜態(tài)庫目錄 # device cargo build --release --target aarch64-apple-ios # simulator arm64 cargo build --release --target aarch64-apple-ios-sim # simulator x86_64 cargo build --release --target x86_64-apple-ios然后把三個目錄組織為device、sim-arm64、sim-x86_64三個文件夾每個文件夾里放頭文件、模塊映射和靜態(tài)庫。最方便的方式是直接用xcodebuild -create-xcframeworkxcodebuild -create-xcframework \ -library target/aarch64-apple-ios/release/libmycore.a \ -headers include \ -library target/aarch64-apple-ios-sim/release/libmycore.a \ -headers include \ -library target/x86_64-apple-ios/release/libmycore.a \ -headers include \ -output mycore.xcframework這個命令把三種切片的靜態(tài)庫和它們的公共頭文件包在同一個 xcframework 目錄里。Xcode 在編譯時自動識別當(dāng)前 target 是 device 還是 simulator并鏈接對應(yīng)切片。集成到 Xcode 時直接把 mycore.xcframework 拖入 target 的 Frameworks 目錄然后在 Build Settings 的FRAMEWORK_SEARCH_PATHS加上它的路徑。在 Xcode 的 Link Binary With Libraries 里加上 MyCore.xcframeworkSwift 側(cè)直接 import MyCore 就能調(diào)用公開函數(shù)。如果你的 xcframework 沒設(shè)置BUILD_LIBRARY_FOR_DISTRIBUTION可能會出現(xiàn)模塊找不到的問題一個臨時解法是把頭文件放到 Header Search Paths 里但更好的方式是讓 Xcode 自動映射 module。4.3 Swift 側(cè)封裝 Rust 函數(shù)CChar 指針與 Data 的互操作Swift 調(diào)用 C 函數(shù)時字符串處理比較繁瑣。我一般封裝成import Foundation public enum Tokenizer { public static func encode(text: String) - [Int64] { let capacity 4096 var ids [Int64](repeating: 0, count: capacity) let count ids.withUnsafeMutableBufferPointer { buffer - Int32 in text.withCString { cString in tokenizer_encode(cString, buffer.baseAddress, Int32(capacity)) } } guard count 0 else { return [] } return Array(ids.prefix(Int(count))) } }重點(diǎn)是withCString和withUnsafeMutableBufferPointer這兩個語法前者保證字符串在調(diào)用期間以 C 字符串形式存在后者保證 ids 數(shù)組的連續(xù)內(nèi)存空間可以被 C 指針寫入。這里面的調(diào)用不拷貝大塊數(shù)據(jù)所以性能可控。對于模型路徑Swift 側(cè)把 Bundle 里的資源路徑轉(zhuǎn)成 C 字符串傳給tokenizer_load_model。注意模型路徑如果包含中文或特殊字符C 字符串的 UTF-8 編碼要統(tǒng)一Swift 的fileSystemRepresentation是更安全的選擇。4.4 資源文件雙端路徑解析Android asset 與 iOS Bundle 的統(tǒng)一邏輯AI 模塊經(jīng)常需要加載詞表和模型文件雙端的路徑機(jī)制完全不同。Android 有 asset 和 file 兩種路徑通過context.getAssets()或者context.getFilesDir()拿到iOS 走Bundle.main.url(forResource:withExtension:)。我為了不把路徑邏輯寫死在 Rust 里設(shè)計了一個“路徑注入”接口Rust 只認(rèn)一個絕對路徑字符串參數(shù)路徑由上層根據(jù)平臺注入。Android 端把 asset 里的文件先解壓到緩存目錄再把緩存路徑傳給 RustiOS 端把 Bundle 中的文件路徑直接傳給 Rust。這樣做的好處是 Rust 的模型加載邏輯完全不感知雙端差異。Android 端偽代碼File modelFile new File(getCacheDir(), model.bin); copyAssetToFile(context, models/model.bin, modelFile); MyRustLib.loadModel(modelFile.getAbsolutePath());iOS 端if let path Bundle.main.path(forResource: model, ofType: bin) { tokenizer_load_model(path) }注意 Android 的 asset 路徑經(jīng)過 copy 后才變成真實(shí)文件路徑iOS 的 Bundle 路徑本身可以直接訪問。這里我踩過的坑是 Android 某些低版本機(jī)型上 asset 解壓到 cache 目錄如果磁盤不足會靜默失敗所以最好在調(diào)用 Rust 前檢查文件長度是否符合預(yù)期。5. 雙端聯(lián)調(diào)常見問題與排查清單5.1 Android 常見崩潰與 JNI 封裝層的自查方法聯(lián)調(diào)階段最容易碰到的錯誤有幾個高頻類型整理成自查清單建議收藏對比。錯誤現(xiàn)象優(yōu)先級排查方向UnsatisfiedLinkError: dlopen failed: library libmycore.so not found高.so 是否在正確 abi 目錄abiFilters 是否排除UnsatisfiedLinkError: JNI_OnLoad not found高Rust 側(cè)是否導(dǎo)出 JNI_OnLoad 符號java.lang.UnsatisfiedLinkError: No implementation found for native method高函數(shù)簽名是否完全匹配包名/類名Process crashed with SIGSEGV緊急Rust 側(cè) panic 是否 catchRead an invalid pointer緊急跨語言傳指針后是否懸垂No implementation found這類問題的排查先用javap -s查看生成的 JNI 簽名再比對 Rust 的函數(shù)名。如果類在com.example.ai.MyRustLib函數(shù)名必須完全匹配Java_com_example_ai_MyRustLib_tokenize包名里的下劃線不要漏內(nèi)部類名用_00024轉(zhuǎn)義。一個建議是讓 JNI 函數(shù)不依賴類名直接提供一個JNI_OnLoad注冊函數(shù)表#[no_mangle] pub extern system fn JNI_OnLoad(env: JNIEnv, _vm: JavaVM) - jint { let class env.find_class(com/example/ai/MyRustLib).unwrap(); // 在這里注冊 native methods函數(shù)名可以自定義不再受命名規(guī)則約束 env.register_native_methods(class, [ JNINativeMethod::new(tokenize, ([I)[I, tokenize_impl), ]).unwrap(); JNI_VERSION_1_6 }這種方式更干凈也更容易在多個類之間共享 Rust 函數(shù)實(shí)現(xiàn)。SIGSEGV 的排查大多數(shù)時候要么是 Rust 內(nèi)部 panic 沒 catch要么是空指針/懸垂指針問題。Rust 代碼里指針操作用std::ptr::NonNull或者OptionT來保護(hù)不要裸用*const。5.2 iOS 聯(lián)調(diào)時 Xcode 報 Undefined Symbols 的幾種典型場景iOS 集成階段最典型的就是鏈接錯誤。如果你看到Undefined symbol: _tokenizer_encode說明 Rust 靜態(tài)庫沒有正確鏈接到 target或者編譯 slice 不匹配。Xcode 的 Build Log 里用-target參數(shù)查看最后一步鏈接了哪個庫。另一個典型問題是 Bitcode。從 Xcode 14 開始 Apple 移除了 Bitcode但早期工程里還留著ENABLE_BITCODE YES的配置。Rust 默認(rèn)不支持 BitcodeXcode 編譯報錯時把 Build Setting 里的 ENABLE_BITCODE 設(shè)置為 NO。模擬器跑起來了真機(jī)卻在這個函數(shù)上崩潰十有八九是 slice 不匹配。確保 xcframework 里 device slice 存在不能只在模擬器環(huán)境下編譯通過就算完事。用lipo -info查看靜態(tài)庫架構(gòu)lipo -info target/aarch64-apple-ios/release/libmycore.a如果只顯示 arm64說明這個庫只支持真機(jī)模擬器切過去會直接報架構(gòu)錯誤。5.3 Rust 側(cè) panic 穿越 FFI 邊界導(dǎo)致的隱蔽崩潰這個問題在 Android 和 iOS 上都會出現(xiàn)而且是所有坑里最隱蔽的。默認(rèn)情況下 Rust 的 panic 會觸發(fā)棧展開但如果跨過了 C ABI 邊界棧展開會試圖處理一個不屬于 Rust 的棧幀結(jié)果通常是直接崩潰。前面提過的std::panic::catch_unwind方案可以兜住大部分 panic但 catch_unwind 只能捕獲 Rust 的 panic如果 panicabort進(jìn)程直接終止連 catch 的機(jī)會都沒有。最好的方案是在Cargo.toml里設(shè)置panic unwind用于開發(fā)release 階段設(shè)置panic abort但所有 FFI 入口都用 catch_unwind 包裹在入口函數(shù)最外層用 catch_unwind 保護(hù)返回一個錯誤碼內(nèi)部邏輯不要使用 unwrap、expect、panic!全部用 Result 傳播。我在實(shí)際項目里把 unwrap 這種調(diào)用寫死在 clippy 的 deny 列表里防止新代碼引入 paniccargo clippy -- -D warnings -D clippy::unwrap_used養(yǎng)成這個習(xí)慣FFI 邊界基本不會再出隱藏崩潰。5.4 符號沖突與 .so 加載順序問題Android 上加載多個 .so 時如果兩個庫里有同名符號后加載的庫可能覆蓋先加載的符號導(dǎo)致 AI 模塊意外調(diào)用到別的庫里同名函數(shù)。這是極其隱蔽的 bug。排查思路用readelf -s libmycore.so | grep查看導(dǎo)出符號把所有 Rust 導(dǎo)出符號用倉庫名加前綴比如mycore_tokenizer_encode避免全局面貌沖突。iOS 靜態(tài)庫不存在運(yùn)行時沖突但鏈接時多個 .a 之間可能有重復(fù)符號Xcode 會直接報 duplicate symbol處理辦法是把不需要的 obj 文件從庫中剔除或者把重復(fù)的符號隱藏到 static 函數(shù)里。正常情況下 Rust 靜態(tài)庫里只有你會調(diào)用的符號但如果 crate 依賴引入了某些全局符號鏈接時會有驚喜。6. 出包自動化的工程化實(shí)踐6.1 用 Justfile 或 Makefile 封裝雙端構(gòu)建腳本避免復(fù)制粘貼命令手動敲構(gòu)建命令試過一兩次就夠了后面一定會寫腳本。我推薦 Justfile 或 Makefile# Makefile ANDROID_NDK : $(ANDROID_NDK_HOME) .PHONY: android ios xcframework android: cargo ndk -t arm64-v8a -t armeabi-v7a -t x86_64 -o ../android/src/main/jniLibs build --release ios: cargo build --release --target aarch64-apple-ios cargo build --release --target aarch64-apple-ios-sim cargo build --release --target x86_64-apple-ios xcframework: ios rm -rf MyCore.xcframework xcodebuild -create-xcframework \ -library target/aarch64-apple-ios/release/libmycore.a -headers include \ -library target/aarch64-apple-ios-sim/release/libmycore.a -headers include \ -library target/x86_64-apple-ios/release/libmycore.a -headers include \ -output MyCore.xcframework release: android xcframework echo release done實(shí)際項目里還會在腳本里做這些事檢查ANDROID_NDK_HOME是否存在自動定位 NDK 版本用cargo test跑一遍 Rust 側(cè)單元測試后再出包用git rev-parse --short HEAD把 commit hash 寫進(jìn)生成物文件名方便回溯上傳產(chǎn)物到內(nèi)部制品庫AAR 走 maven 私服xcframework 直接打包上傳或通過 SwiftPM 分發(fā)。6.2 CI 流水線里按架構(gòu)并行構(gòu)建顯著縮短雙端出包時間在 GitHub Actions 或自建 CI 上把各 target 構(gòu)建分到不同 job 并行跑能省一半以上時間。Android 和 iOS 的交叉編譯不互相依賴流水線大致分為Rust lint 單元測試并行 jobAndroid 三 ABI 構(gòu)建 iOS 三 slice 構(gòu)建匯聚打 AAR / 生成 xcframework上傳產(chǎn)物舉個 GitHub Actions 的關(guān)鍵片段jobs: android: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: dtolnay/rust-toolchainstable with: targets: aarch64-linux-android,armv7-linux-androideabi,x86_64-linux-android - uses: nttld/setup-ndkv1 id: ndk with: ndk-version: r25c - run: cargo ndk -t arm64-v8a -t armeabi-v7a -t x86_64 -o out/jniLibs build --releaseiOS 構(gòu)建必須有 macOS 環(huán)境的 runnermacos-latest或者自建 mac 節(jié)點(diǎn)都行。注意dtolnay/rust-toolchain的targets參數(shù)一次同時添加所有 target省掉后面手動 rustup target add。6.3 版本規(guī)范化Rust crate 版本、AAR 版本和 xcframework 版本如何對齊雙端集成最怕版本漂移Android 上跑到 1.2.0 的 Rust 核心iOS 上還是 1.1.0AI 模型輸入輸出就可能對不上。我在項目里做了一個約定Rust crate 版本是唯一真源寫在Cargo.toml的version字段。Android 的 library module 用gradle的version屬性傳參構(gòu)建腳本自動從 Cargo.toml 讀取版本寫入 generated 文件。iOS 的 xcframework 產(chǎn)物目錄里包含版本號MyCore-1.2.0.xcframework并且安裝進(jìn) Xcode 后可以在 Info.plist 里寫入版本描述。# 從 Cargo.toml 讀取版本號 VERSION$(grep ^version Cargo.toml | sed s/.*\(.*\)/\1/)腳本把這個版本寫入 Android 的 BuildConfig 和 iOS 的 Info.plist。兩邊在啟動時上報版本號如果差異過大直接提示強(qiáng)制更新這是聯(lián)調(diào)階段省心省力的關(guān)鍵一步。模型文件也建議打上同版本號。AI 模塊模型文件如果和 Rust 邏輯不是同一版本輕則推理結(jié)果差重則直接內(nèi)存越界。我的做法是模型文件名帶 hash構(gòu)建腳本從模型服務(wù)器下載時自動匹配 hash避免“路徑同名但內(nèi)容不同”的事故。7. 實(shí)操心得與最后的小補(bǔ)充先說我最直觀的感受Rust 雙端集成這件事難度不在于 Rust 本身而在于對整個工具鏈的耐心。Android 的 JNI 簽名、iOS 的 slice 組合、NDK 路徑、Bitcode 關(guān)閉每一個環(huán)節(jié)單獨(dú)拎出來都是半小時能解決的但串在一起就是好幾個晚上。如果你第一次做建議按“一個平臺先跑通再復(fù)制到另一個平臺”的節(jié)奏來。不要一上來就雙端并行不然出錯時你會分不清是 Rust 邏輯問題還是集成問題。我第二次做這個方案時把整個流程簡化成了兩個 make 命令“make android” 和 “make xcframework”集成文檔寫了一頁 A4 紙新同事半天就能跑通。你如果是在團(tuán)隊里推廣 Rust 移動端方案完全可以按這個思路來先花兩個晚上把腳本和文檔沉淀好后面所有人的時間都會被省回來。一個小技巧分享給你如果你 Debug 階段想在 Android Studio 里直接跑 Rust 側(cè)單元測試不要只在 target 上編 .so在宿主機(jī)上跑cargo test會更舒服。Rust 側(cè)業(yè)務(wù)邏輯和 JNI 解耦得越干凈這個測試就越好用。接口層只有薄薄一層 JNI 語法而真正復(fù)雜的算法都在my_corecrate 里單元測試全跑在開發(fā)機(jī)上整個迭代速度會快到你不適應(yīng)。最后提醒一個冷門但致命的事情iOS 靜態(tài)庫如果開啟了某些 Rust crate 的std特性但它依賴了系統(tǒng)動態(tài)庫例如libsqlite3或libz鏈接時你會看到怪異的 undefined symbol。這時候在 Xcode 里手動加對應(yīng)的系統(tǒng) framework 或-lz -lsqlite3鏈接參數(shù)就能修復(fù)。Android 也有類似問題target 平臺缺系統(tǒng)庫時會報 dlopen 錯誤。做集成之前先跑一遍依賴樹分析大概率能避開后面一半的坑。