4、环境搭建与交叉编译：Android NDK环境配置，iOS Xcode工具链，ONNX Runtime Mobile源码编译，交叉编译参数详解（CPU、GPU、NPU）
说实话，环境搭建这件事，看着简单，做起来全是坑。
我见过太多同学，模型在PC上跑得飞起，一上手机就崩。为什么？交叉编译工具链没配好。今天咱们就把这事彻底捋清楚。
4.1 Android NDK 环境配置
Android NDK，说白了就是让你能在Android上跑C++代码的工具集。我刚开始搞的时候，以为装个NDK就行了，结果编译出来的so库一运行就段错误。后来才发现，API级别和ABI架构必须严格对应。
我的推荐配置：
- NDK版本：r25c 或 r26b（太新的版本可能有兼容性问题）
- 最低API级别：24（覆盖99%的存量设备）
- 目标ABI：arm64-v8a（主力），armeabi-v7a（兼容）
关键点：NDK的安装路径不要带空格，不要用中文。我吃过这个亏，CMake报错查了两天才发现是路径问题。
配置步骤其实就三步：
- 下载NDK并解压到
~/Android/Sdk/ndk/ - 设置环境变量
export ANDROID_NDK_HOME=~/Android/Sdk/ndk/r25c - 验证：运行
$ANDROID_NDK_HOME/ndk-build --version
# 我的常用NDK环境变量配置（加到 ~/.zshrc 或 ~/.bashrc）
export ANDROID_NDK_HOME=$HOME/Android/Sdk/ndk/r25c
export ANDROID_SDK_ROOT=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin
export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools
小技巧：用 adb shell getprop ro.product.cpu.abi 查看真机的ABI类型。别信文档，信真机。
4.2 iOS Xcode 工具链
iOS这边相对省心，因为Xcode帮你管好了大部分事情。但有个问题——Xcode版本和iOS SDK版本必须匹配。我遇到过用Xcode 15编译的库，在iOS 16的设备上跑，Metal API调用直接闪退。
我的经验：
- Xcode 15.0+ 对应 iOS 17 SDK
- Xcode 14.3+ 对应 iOS 16 SDK
- 最低部署目标：iOS 14（再低就没人用了）
交叉编译时，架构选择要注意：
| 架构 | 设备 | 是否必需 |
|---|---|---|
| arm64 | iPhone 5s 及以后 | 是 |
| x86_64 | 模拟器 | 调试用 |
我个人习惯用 xcodebuild 命令行编译，而不是在Xcode GUI里点来点去。这样能写脚本自动化，也方便CI集成。
# iOS交叉编译示例（arm64）
xcodebuild \
-project YourProject.xcodeproj \
-scheme YourScheme \
-sdk iphoneos \
-arch arm64 \
-configuration Release \
IPHONEOS_DEPLOYMENT_TARGET=14.0
注意：如果你用了CocoaPods或Swift Package Manager，记得先 pod install 或解析SPM依赖。否则编译会报找不到头文件。
4.3 ONNX Runtime Mobile 源码编译
ONNX Runtime Mobile，官方叫ORT Mobile。它比完整版ORT小很多，专门为移动端裁剪过。但源码编译这件事，官方文档写得不够细。
为什么非要自己编译？
- 官方预编译包不一定包含你需要的算子
- 你可能需要开启特定加速后端（如NNAPI、CoreML）
- 二进制大小有严格限制时，可以按需裁剪
编译ORT Mobile，核心是配置 build.sh 的参数。我踩过最深的坑是——忘了指定 --minimal_build，结果编译出来的so库有80MB，根本没法用。
# Android ARM64 编译ORT Mobile（我的常用配置）
./build.sh \
--config Release \
--android \
--android_abi arm64-v8a \
--android_api 24 \
--minimal_build \
--enable_onnx_tests=OFF \
--parallel \
--skip_tests
# iOS arm64 编译
./build.sh \
--config Release \
--ios \
--ios_arch arm64 \
--minimal_build \
--enable_onnx_tests=OFF \
--parallel
核心参数说明：
--minimal_build：开启最小化编译，只保留必要算子--enable_onnx_tests=OFF：跳过测试，节省编译时间--parallel：多核编译，能快3-5倍
编译产物在 build/<平台>/Release/ 下。你会看到 libonnxruntime.so（Android）或 libonnxruntime.a（iOS）。
4.4 交叉编译参数详解（CPU、GPU、NPU）
交叉编译，说白了就是在一台机器上生成另一台机器能跑的代码。但不同硬件后端，参数差异很大。
CPU 后端：
最基础，也最稳。编译时主要关注指令集优化。
- Android：
-march=armv8-a+fp+simd - iOS：默认开启NEON，不需要额外参数
- 量化推理：
-DORT_ENABLE_QUANTIZATION=ON
GPU 后端：
这里坑最多。Android用OpenCL或Vulkan，iOS用Metal。
- Android Vulkan：
--use_vulkan，需要NDK r23+ - Android OpenCL：需要手动链接OpenCL库，不同厂商的库不通用
- iOS Metal：
--use_metal，Xcode 12+
我曾经踩过的坑：在骁龙888上编译了Vulkan后端，结果在麒麟9000上跑，驱动版本不兼容，直接crash。后来我加了运行时检测：vkEnumerateInstanceVersion 检查Vulkan版本，低于1.1就回退到CPU。
NPU 后端：
NPU各家不通用，需要单独适配。
| 平台 | NPU方案 | 编译参数 |
|---|---|---|
| 高通 | QNN（Qualcomm Neural Network） | --use_qnn |
| 联发科 | NeuroPilot | --use_neuropilot |
| 华为 | HiAI / DaVinci | --use_hiai |
| 苹果 | ANE（Apple Neural Engine） | --use_coreml |
你想想看，如果想把一个模型同时跑在骁龙和天玑上，就得编译两个不同后端的ORT版本。这也是为什么我建议在代码里做运行时切换——编译时只编CPU+GPU，NPU用动态库加载。
4.5 知识结构总览
下面这张图，是我自己梳理的交叉编译知识体系。每次配新环境，我都按这个流程走一遍。
我的建议：第一次编译时，先只编CPU后端。跑通了再逐步加GPU、NPU。否则问题混在一起，你根本不知道是编译参数错了，还是代码逻辑有问题。
嗯，环境搭建这部分，说白了就是耐心活。别指望一次成功，我每次配新环境至少编译3-5次才能跑通。但只要你把NDK、Xcode、ORT Mobile这三个核心环节的配置参数吃透了，后面的事情就顺了。