從寫 Rust 代碼到真正把 .so 塞進(jìn) Android、把 xcframework 塞進(jìn) iOS中間隔著一整條工具鏈、鏈接器、ABI 和打包規(guī)范的鴻溝。這堂課我把雙端集成的完整路徑梳理了一遍Android 端從 jni 接口到 AAR 打包iOS 端從 C FFI 到 xcframework 生成最后講清楚我在兩端聯(lián)調(diào)時(shí)踩過的那些坑。如果你正在做 AI 推理、數(shù)據(jù)預(yù)處理或者任何需要 Rust 高性能模塊的移動(dòng)端交付這篇可以直接照著走。先說結(jié)論Rust 寫業(yè)務(wù)邏輯只是第一步真正的工程量在“跨語言邊界”和“出包產(chǎn)物”上。Android 要的是 AAR 里裹著 jniLibs/*.soiOS 要的是 xcframework 里躺著不同架構(gòu)的靜態(tài)庫或動(dòng)態(tài)庫兩端各有一套 ABI 體系但 Rust 源碼可以完全共用。這就是這門課的核心邏輯——用 Rust 的統(tǒng)一實(shí)現(xiàn)換雙端一致的運(yùn)行行為省掉兩套原生代碼的重復(fù)開發(fā)和維護(hù)。1. 項(xiàng)目整體設(shè)計(jì)與雙端底層邏輯拆解1.1 為什么 AI 模塊用 Rust而不是 Kotlin/Java 或 Swift/ObjC我的場景是這樣的底層的 tokenizer 和 embedding 計(jì)算用 C 寫了一版效果沒問題但跨端維護(hù)成本太高。Android 端 JNI 調(diào) C、iOS 端 bridge 調(diào) C兩邊簽名靠手寫頭文件維護(hù)AI 模型和推理 runtime 升級一次就要兩端同步改一輪。后來把核心模塊用 Rust 重寫之后整個(gè)交付邏輯清晰了很多。Rust 在 AI 模塊里的核心優(yōu)勢用大白話講有三點(diǎn)第一是內(nèi)存安全與計(jì)算性能能同時(shí)拿到。AI 推理里大量高頻的向量運(yùn)算、矩陣乘、字符串編碼C 做起來要小心越界和懸垂指針Rust 在保證內(nèi)存安全的條件下做了零成本抽象循環(huán)展開、SIMD 優(yōu)化這些都能直接享受。用criterion做基準(zhǔn)測試同樣的 tokenizer 邏輯Rust 版本和 C 版本性能在同一量級但我?guī)缀醪挥迷倩〞r(shí)間追內(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ù)框架而是提供一個(gè)“可以用 FFI 調(diào)用的高性能計(jì)算內(nèi)核”。第三是二進(jìn)制體積和啟動(dòng)性能可控。Rust 的 release 構(gòu)建經(jīng)過opt-levelz和ltotrue優(yōu)化后一個(gè)獨(dú)立的 .so 或 .a 往往只有幾百 KB 到幾 MB。移動(dòng)端對包體積很敏感AI 模塊做小留給模型文件的空間就更大。這選的代價(jià)是調(diào)用雙方必須通過 FFI 邊界字符串、數(shù)組、回調(diào)都要做一層序列化和指針轉(zhuǎn)換。我的目標(biāo)就是把這一層做得足夠薄讓 AI 模塊內(nèi)部可以專注計(jì)算邏輯而把 Java/Kotlin 和 Swift 的類型系統(tǒng)“翻譯”工作收斂在接口層。1.2 兩端交付形態(tài)的核心差異JNI 動(dòng)態(tài)鏈路 vs C FFI 靜態(tài)鏈路Android 和 iOS 雖然都是用 C ABI 作為 Rust 和其他語言之間的“通用語言”但工程形態(tài)完全不同。Android 用的 JNIJava Native Interface。Rust 編譯產(chǎn)物是.so動(dòng)態(tài)庫JVM 通過System.loadLibrary(xxx)在運(yùn)行時(shí)加載它。JNI 要求函數(shù)名必須按照規(guī)范簽名比如Java_com_example_MyClass_nativeMethod還要處理 JNIEnv 指針、jobject 引用這些東西。這套機(jī)制足夠靈活但動(dòng)態(tài)庫的初始化時(shí)機(jī)、不同 ABI 目錄arm64-v8a、armeabi-v7a、x86_64的兼容性都要在出包時(shí)謹(jǐn)慎處理。iOS 走的是標(biāo)準(zhǔn) C 符號鏈接。如果 Rust 編成.a靜態(tài)庫鏈接進(jìn) App 可執(zhí)行文件里就不涉及運(yùn)行時(shí)動(dòng)態(tài)加載如果編成.dylib還要處理簽名和 embed 的問題。實(shí)踐上首選靜態(tài)庫配合 xcframework 把模擬器和真機(jī)切片打包在一起Xcode 在編譯時(shí)自動(dòng)挑合適的架構(gòu)。表格對比更直觀維度AndroidiOSRust 產(chǎn)物.so 動(dòng)態(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è)計(jì)與跨語言數(shù)據(jù)傳遞2.1 接口層該暴露什么、藏什么一個(gè) AI 推理模塊的接口設(shè)計(jì)我接手的項(xiàng)目里Rust 核心模塊承擔(dān)了三個(gè)職責(zé)加載 tokenizer 詞表、字符串編碼成 token IDs、調(diào)用 ONNX runtime 做推理。Android/iOS 上層需要拿到的是 int 數(shù)組token IDs、String解碼結(jié)果以及狀態(tài)碼成功/失敗。我的設(shè)計(jì)原則是“一個(gè)公開函數(shù)只干一件大事返回值盡量是簡單類型”。拿 tokenizer 舉例Java 層需要的就是String[] tokenize(String text)或者更高效的int[] tokenize(String text)——把字符串轉(zhuǎn)換成一組 id。在 JNI 層我不會(huì)直接返回 Java 對象而是返回一個(gè)jlong指針指向 Rust 側(cè)一個(gè)常量字符串?dāng)?shù)組或字節(jié)數(shù)組然后由 JNI 封裝層把它轉(zhuǎn)換成 Java 數(shù)組。為什么這么做跨語言邊界最怕的就是對象生命周期管理Java 持有 Rust 分配的內(nèi)存如果不主動(dòng)釋放就是泄漏讓 JNI 層每次調(diào)用時(shí)把數(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 }這個(gè)函數(shù)表面上是 tokenize但它在 ABI 層面的真實(shí)身份是 JNI 入口參數(shù)里帶著 JNIEnv 指針。這里的extern system很關(guān)鍵它保證符號按 C 調(diào)用約定導(dǎo)出而不是 Rust 的加殼約定。Java 層調(diào)用時(shí)傳入一個(gè) String拿到一個(gè) int[]整個(gè)過程走的是 JNI 的 GetStringUTFChars / NewIntArray 的底層機(jī)制但 Rust 側(cè)封裝好了不需要手動(dòng)碰 C 字符串指針。2.2 從 Rust 返回字符串、數(shù)組和錯(cuò)誤碼時(shí)容易忽略的細(xì)節(jié)字符串跨語言傳遞是我踩過最多坑的地方。JNI 的get_string拿到的是JString轉(zhuǎn)成 Rust String 是拷貝操作這個(gè)開銷在 tokenize 這種高頻函數(shù)上積少成多。等成本優(yōu)化后我會(huì)在接口層做一個(gè)緩沖復(fù)用如果輸入長度在某個(gè)范圍內(nèi)直接復(fù)用 JNI 側(cè)的一塊固定緩沖區(qū)減少 JNI 調(diào)用的分配次數(shù)。返回字符串時(shí)我習(xí)慣返回jstring而不是*const c_char。原因很簡單Java 層原生處理 String 最方便JNI 的env.new_string()可以直接包裝 Rust 字符串。但是要注意new_string接收的是 JNI 的修改過的 UTF-8 字符串碰到超長字符串和特殊字符時(shí)要謹(jǐn)慎盡量先用 Java 側(cè)做編碼轉(zhuǎn)換保證數(shù)據(jù)一致。錯(cuò)誤碼統(tǒng)一用整數(shù)0 表示成功負(fù)數(shù)表示不同的錯(cuò)誤類型。比如 tokenizer 加載失敗返回 -1模型推理超時(shí)返回 -2參數(shù)錯(cuò)誤返回 -3。Java 層和 Swift 層各自寫一個(gè)枚舉映射不需要跨語言拋異常——跨語言拋異常這件事在 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)會(huì) unwinding越過了 FFI 邊界是未定義行為這在移動(dòng)端是致命的。一定要在入口函數(shù)里設(shè)置 panic 捕獲#[no_mangle] pub extern system fn Java_com_example_ai_MyRustLib_tokenize(...) - jintArray { std::panic::catch_unwind(|| { // 原有邏輯 }) .unwrap_or_else(|_| { // 返回空數(shù)組或錯(cuò)誤碼 }) }這一條幾乎所有的入門教程都沒講但缺了它生產(chǎn)環(huán)境的崩潰率直接上升一個(gè)量級。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時(shí)會(huì)檢查空指針和 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 指針操作收斂到一個(gè)文件里上層業(yè)務(wù)完全不感知 C 的存在。這就是對稱性Android 的 JNI 封裝層和 iOS 的 Swift 封裝層雖然在語法上天差地別但設(shè)計(jì)模式都是“把 FFI 邊界封裝在一個(gè)模塊里上層只面對普通的類型”。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三個(gè) target 分別對應(yīng) arm64-v8a、armeabi-v7a、x86_64。x86_64 通常只用于模擬器但 CI 里跑測試會(huì)用到。這里的關(guān)鍵點(diǎn)是 NDK 工具鏈Rust 在編譯時(shí)會(huì)調(diào)用 NDK 里的 clang 和鏈接器需要 ndk 路徑。我在項(xiàng)目的.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最好編一個(gè) 26 的 clang避免運(yùn)行時(shí)鏈接到不存在的 libc 符號。強(qiáng)烈建議不要手動(dòng)寫路徑用環(huán)境變量ANDROID_NDK_HOME替代腳本里動(dòng)態(tài)拼鏈接器路徑否則換個(gè) NDK 版本整個(gè)工程就廢了。構(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)于讓整個(gè)進(jìn)程直接 abort而不走 unwinding。所以我在入口函數(shù)里用catch_unwind把所有邏輯兜住這樣 panic 不會(huì)穿過 FFI 邊界進(jìn)程也不會(huì)崩最壞情況是錯(cuò)誤碼歸 -1。3.2 用 cargo-ndk 一鍵產(chǎn)出多 ABI 的 .so如果獨(dú)立項(xiàng)目追求效率直接上cargo-ndkcargo install cargo-ndk cargo ndk -t arm64-v8a -t armeabi-v7a -t x86_64 -o ../android/src/main/jniLibs build --release這個(gè)命令會(huì)同時(shí)生成三種 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 識別如果項(xiàng)目是純 Android 工程放到 src/main/jniLibs 下就完事了。如果 Rust 是獨(dú)立工作區(qū)把 .so 文件拷貝過去即可。這里有個(gè)細(xì)節(jié)lib前綴不能丟。Android 的 System.loadLibrary 會(huì)自動(dòng)補(bǔ)這層前綴但如果你的 .so 文件名不是lib開頭就加載不到。3.3 手動(dòng)拼 AAR把 jniLibs、manifest 和 ProGuard 規(guī)則塞進(jìn)去如果不想依賴 Android Studio 的 Gradle 插件自動(dòng)生成 AAR可以手動(dòng)構(gòu)造。AAR 本質(zhì)上是一個(gè) 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一個(gè)標(biāo)準(zhǔn) AAR 必須有AndroidManifest.xml和classes.jar即使 Manifest 內(nèi)容為空也要存在R.txt也是空的也可能被 Gradle 讀取。手動(dòng) zip 時(shí)名字必須是.aar。比如我寫了一個(gè)MyRustLib.java把它編譯成 classes.jar 塞進(jìn) AAR上層 Module 通過compileOnly或api依賴這個(gè) AAR就能直接調(diào)用MyRustLib.tokenize()。jni 目錄下按 ABI 分文件夾Gradle 在最終打包 APK 時(shí)會(huì)根據(jù)主 App 的 abiFilters 自動(dòng)選擇包含哪些 .so。實(shí)際上我通常在項(xiàng)目里直接用 Android Library Module 來管理 Rust 產(chǎn)物而不是手動(dòng)拼 AAR。流程是新建 Android Library 模塊把 Rust 生成的 jniLibs 放進(jìn)src/main/jniLibs然后在同一個(gè)模塊里寫 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)會(huì)打包所有 ABIAPK 體積變大是一回事更重要的是某些 ABI比如 mips在真實(shí)設(shè)備上根本運(yùn)行不了。加載 .so 的位置也很有講究。JNI 規(guī)范里要求System.loadLibrary在類初始化的時(shí)候被調(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)境下多個(gè)線程同時(shí)進(jìn)入 loadLibrary 驅(qū)動(dòng)會(huì)偶發(fā)錯(cuò)誤。另外一個(gè)老坑你的 App 如果引用了其他第三方庫它們內(nèi)部可能也帶 soJNI 庫名沖突會(huì)導(dǎo)致加載失敗。另外一個(gè)常見問題是 minSdk 與 JNI 函數(shù)簽名無關(guān)但和 .so 的 ELF 版本有關(guān)。如果你編的 so 里面引用了高版本 Android 才有的符號在低版本系統(tǒng)上加載時(shí)會(huì)報(bào)UnsatisfiedLinkError。保持 minSdk 26 以上基本可以避開大多兼容性問題。4. iOS 實(shí)操多架構(gòu)靜態(tài)庫與 xcframework 生成全流程4.1 iOS 平臺架構(gòu)解析真機(jī)、模擬器和 Rosetta 的取舍iOS 的架構(gòu)體系比 Android 簡單但有一個(gè)特殊點(diǎn)模擬器。目前的模擬器分兩種Apple Silicon Mac 上跑的是aarch64-apple-ios-simIntel Mac 上跑的是x86_64-apple-ios。第一次用 Rust 編 iOS 庫的人百分之百會(huì)在這里迷路——你至少需要三種切片切片對應(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 自動(dòng)處理。添加 targetrustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios編靜態(tài)庫時(shí)不需要鏈接器配置因?yàn)?iOS 上 Rust 不產(chǎn)生動(dòng)態(tài)庫不讓設(shè)置 dylib。如果是編 cdylib 用于測試另說正式集成一律staticlib。在 Cargo.toml 中設(shè)置 crate-type[lib] name mycore crate-type [staticlib, cdylib]編譯時(shí)用cargo build --release --target aarch64-apple-ios生成的靜態(tài)庫在target/aarch64-apple-ios/release/libmycore.a。iOS 側(cè)沒有 JNI 那種運(yùn)行時(shí)系統(tǒng)調(diào)用約束純靜態(tài)鏈接最省心簽名、權(quán)限、隱私這些完全走 App 的正常流程。4.2 用 xcodebuild 打包 xcframeworkXcode 集成時(shí)如何選擇切片早期 iOS 工程都是用 lipo 把多個(gè)架構(gòu)合并成一個(gè) fat 庫但 Apple 在 Xcode 12 之后推薦用 xcframework因?yàn)樗苷_表達(dá)每個(gè)切片對應(yīng)的平臺和架構(gòu)而不是一個(gè) fat 二進(jìn)制里到處放。xcframework 的生成命令# 先生成三個(gè)靜態(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然后把三個(gè)目錄組織為device、sim-arm64、sim-x86_64三個(gè)文件夾每個(gè)文件夾里放頭文件、模塊映射和靜態(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這個(gè)命令把三種切片的靜態(tài)庫和它們的公共頭文件包在同一個(gè) xcframework 目錄里。Xcode 在編譯時(shí)自動(dòng)識別當(dāng)前 target 是 device 還是 simulator并鏈接對應(yīng)切片。集成到 Xcode 時(shí)直接把 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可能會(huì)出現(xiàn)模塊找不到的問題一個(gè)臨時(shí)解法是把頭文件放到 Header Search Paths 里但更好的方式是讓 Xcode 自動(dòng)映射 module。4.3 Swift 側(cè)封裝 Rust 函數(shù)CChar 指針與 Data 的互操作Swift 調(diào)用 C 函數(shù)時(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這兩個(gè)語法前者保證字符串在調(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è)計(jì)了一個(gè)“路徑注入”接口Rust 只認(rèn)一個(gè)絕對路徑字符串參數(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 目錄如果磁盤不足會(huì)靜默失敗所以最好在調(diào)用 Rust 前檢查文件長度是否符合預(yù)期。5. 雙端聯(lián)調(diào)常見問題與排查清單5.1 Android 常見崩潰與 JNI 封裝層的自查方法聯(lián)調(diào)階段最容易碰到的錯(cuò)誤有幾個(gè)高頻類型整理成自查清單建議收藏對比。錯(cuò)誤現(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)義。一個(gè)建議是讓 JNI 函數(shù)不依賴類名直接提供一個(gè)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 }這種方式更干凈也更容易在多個(gè)類之間共享 Rust 函數(shù)實(shí)現(xiàn)。SIGSEGV 的排查大多數(shù)時(shí)候要么是 Rust 內(nèi)部 panic 沒 catch要么是空指針/懸垂指針問題。Rust 代碼里指針操作用std::ptr::NonNull或者OptionT來保護(hù)不要裸用*const。5.2 iOS 聯(lián)調(diào)時(shí) Xcode 報(bào) Undefined Symbols 的幾種典型場景iOS 集成階段最典型的就是鏈接錯(cuò)誤。如果你看到Undefined symbol: _tokenizer_encode說明 Rust 靜態(tài)庫沒有正確鏈接到 target或者編譯 slice 不匹配。Xcode 的 Build Log 里用-target參數(shù)查看最后一步鏈接了哪個(gè)庫。另一個(gè)典型問題是 Bitcode。從 Xcode 14 開始 Apple 移除了 Bitcode但早期工程里還留著ENABLE_BITCODE YES的配置。Rust 默認(rèn)不支持 BitcodeXcode 編譯報(bào)錯(cuò)時(shí)把 Build Setting 里的 ENABLE_BITCODE 設(shè)置為 NO。模擬器跑起來了真機(jī)卻在這個(gè)函數(shù)上崩潰十有八九是 slice 不匹配。確保 xcframework 里 device slice 存在不能只在模擬器環(huán)境下編譯通過就算完事。用lipo -info查看靜態(tài)庫架構(gòu)lipo -info target/aarch64-apple-ios/release/libmycore.a如果只顯示 arm64說明這個(gè)庫只支持真機(jī)模擬器切過去會(huì)直接報(bào)架構(gòu)錯(cuò)誤。5.3 Rust 側(cè) panic 穿越 FFI 邊界導(dǎo)致的隱蔽崩潰這個(gè)問題在 Android 和 iOS 上都會(huì)出現(xiàn)而且是所有坑里最隱蔽的。默認(rèn)情況下 Rust 的 panic 會(huì)觸發(fā)棧展開但如果跨過了 C ABI 邊界棧展開會(huì)試圖處理一個(gè)不屬于 Rust 的棧幀結(jié)果通常是直接崩潰。前面提過的std::panic::catch_unwind方案可以兜住大部分 panic但 catch_unwind 只能捕獲 Rust 的 panic如果 panicabort進(jìn)程直接終止連 catch 的機(jī)會(huì)都沒有。最好的方案是在Cargo.toml里設(shè)置panic unwind用于開發(fā)release 階段設(shè)置panic abort但所有 FFI 入口都用 catch_unwind 包裹在入口函數(shù)最外層用 catch_unwind 保護(hù)返回一個(gè)錯(cuò)誤碼內(nèi)部邏輯不要使用 unwrap、expect、panic!全部用 Result 傳播。我在實(shí)際項(xiàng)目里把 unwrap 這種調(diào)用寫死在 clippy 的 deny 列表里防止新代碼引入 paniccargo clippy -- -D warnings -D clippy::unwrap_used養(yǎng)成這個(gè)習(xí)慣FFI 邊界基本不會(huì)再出隱藏崩潰。5.4 符號沖突與 .so 加載順序問題Android 上加載多個(gè) .so 時(shí)如果兩個(gè)庫里有同名符號后加載的庫可能覆蓋先加載的符號導(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)行時(shí)沖突但鏈接時(shí)多個(gè) .a 之間可能有重復(fù)符號Xcode 會(huì)直接報(bào) duplicate symbol處理辦法是把不需要的 obj 文件從庫中剔除或者把重復(fù)的符號隱藏到 static 函數(shù)里。正常情況下 Rust 靜態(tài)庫里只有你會(huì)調(diào)用的符號但如果 crate 依賴引入了某些全局符號鏈接時(shí)會(huì)有驚喜。6. 出包自動(dòng)化的工程化實(shí)踐6.1 用 Justfile 或 Makefile 封裝雙端構(gòu)建腳本避免復(fù)制粘貼命令手動(dòng)敲構(gòu)建命令試過一兩次就夠了后面一定會(huì)寫腳本。我推薦 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í)際項(xiàng)目里還會(huì)在腳本里做這些事檢查ANDROID_NDK_HOME是否存在自動(dòng)定位 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)建顯著縮短雙端出包時(shí)間在 GitHub Actions 或自建 CI 上把各 target 構(gòu)建分到不同 job 并行跑能省一半以上時(shí)間。Android 和 iOS 的交叉編譯不互相依賴流水線大致分為Rust lint 單元測試并行 jobAndroid 三 ABI 構(gòu)建 iOS 三 slice 構(gòu)建匯聚打 AAR / 生成 xcframework上傳產(chǎn)物舉個(gè) 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ù)一次同時(shí)添加所有 target省掉后面手動(dòng) rustup target add。6.3 版本規(guī)范化Rust crate 版本、AAR 版本和 xcframework 版本如何對齊雙端集成最怕版本漂移Android 上跑到 1.2.0 的 Rust 核心iOS 上還是 1.1.0AI 模型輸入輸出就可能對不上。我在項(xiàng)目里做了一個(gè)約定Rust crate 版本是唯一真源寫在Cargo.toml的version字段。Android 的 library module 用gradle的version屬性傳參構(gòu)建腳本自動(dòng)從 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/)腳本把這個(gè)版本寫入 Android 的 BuildConfig 和 iOS 的 Info.plist。兩邊在啟動(dòng)時(shí)上報(bào)版本號如果差異過大直接提示強(qiáng)制更新這是聯(lián)調(diào)階段省心省力的關(guān)鍵一步。模型文件也建議打上同版本號。AI 模塊模型文件如果和 Rust 邏輯不是同一版本輕則推理結(jié)果差重則直接內(nèi)存越界。我的做法是模型文件名帶 hash構(gòu)建腳本從模型服務(wù)器下載時(shí)自動(dòng)匹配 hash避免“路徑同名但內(nèi)容不同”的事故。7. 實(shí)操心得與最后的小補(bǔ)充先說我最直觀的感受Rust 雙端集成這件事難度不在于 Rust 本身而在于對整個(gè)工具鏈的耐心。Android 的 JNI 簽名、iOS 的 slice 組合、NDK 路徑、Bitcode 關(guān)閉每一個(gè)環(huán)節(jié)單獨(dú)拎出來都是半小時(shí)能解決的但串在一起就是好幾個(gè)晚上。如果你第一次做建議按“一個(gè)平臺先跑通再復(fù)制到另一個(gè)平臺”的節(jié)奏來。不要一上來就雙端并行不然出錯(cuò)時(shí)你會(huì)分不清是 Rust 邏輯問題還是集成問題。我第二次做這個(gè)方案時(shí)把整個(gè)流程簡化成了兩個(gè) make 命令“make android” 和 “make xcframework”集成文檔寫了一頁 A4 紙新同事半天就能跑通。你如果是在團(tuán)隊(duì)里推廣 Rust 移動(dòng)端方案完全可以按這個(gè)思路來先花兩個(gè)晚上把腳本和文檔沉淀好后面所有人的時(shí)間都會(huì)被省回來。一個(gè)小技巧分享給你如果你 Debug 階段想在 Android Studio 里直接跑 Rust 側(cè)單元測試不要只在 target 上編 .so在宿主機(jī)上跑cargo test會(huì)更舒服。Rust 側(cè)業(yè)務(wù)邏輯和 JNI 解耦得越干凈這個(gè)測試就越好用。接口層只有薄薄一層 JNI 語法而真正復(fù)雜的算法都在my_corecrate 里單元測試全跑在開發(fā)機(jī)上整個(gè)迭代速度會(huì)快到你不適應(yīng)。最后提醒一個(gè)冷門但致命的事情iOS 靜態(tài)庫如果開啟了某些 Rust crate 的std特性但它依賴了系統(tǒng)動(dòng)態(tài)庫例如libsqlite3或libz鏈接時(shí)你會(huì)看到怪異的 undefined symbol。這時(shí)候在 Xcode 里手動(dòng)加對應(yīng)的系統(tǒng) framework 或-lz -lsqlite3鏈接參數(shù)就能修復(fù)。Android 也有類似問題target 平臺缺系統(tǒng)庫時(shí)會(huì)報(bào) dlopen 錯(cuò)誤。做集成之前先跑一遍依賴樹分析大概率能避開后面一半的坑。