在Ubuntu 20.04上编译OnnxRuntime C++库，我踩过的那些坑（附完整配置流程）
在Ubuntu 20.04上编译OnnxRuntime C++库：避坑指南与实战经验
当你在Ubuntu 20.04上尝试为C++项目集成OnnxRuntime时，可能会遇到各种意想不到的问题。作为一个在多个生产环境中部署过OnnxRuntime的开发者，我经历过几乎所有常见的编译陷阱。这篇文章不仅会提供完整的配置流程，更重要的是分享那些官方文档没有提及的"坑"和解决方案。
1. 环境准备：那些容易被忽视的细节
在开始编译OnnxRuntime之前，环境配置是第一个容易出错的环节。很多人以为简单地安装CMake和GCC就够了，但实际上远不止如此。
1.1 系统依赖的完整清单
首先，确保你的Ubuntu 20.04系统已经更新到最新状态：
sudo apt update && sudo apt upgrade -y然后安装这些必需的依赖项：
sudo apt install -y build-essential cmake git python3-dev python3-pip libssl-dev libgtest-dev libgoogle-glog-dev libprotobuf-dev protobuf-compiler注意：libgtest-dev和libgoogle-glog-dev虽然不是OnnxRuntime的直接依赖，但缺少它们会导致某些测试工具编译失败，即使你使用了--skip_tests选项。
1.2 Python环境的特殊要求
OnnxRuntime的构建系统实际上依赖Python环境，即使你只编译C++库。我推荐使用conda创建一个隔离环境：
conda create -n onnx_build python=3.8 conda activate onnx_build pip install numpy wheel为什么选择Python 3.8？因为这是OnnxRuntime构建系统最稳定的支持版本。使用3.9或更高版本可能会导致一些难以诊断的构建错误。
2. 获取源代码：国内开发者的特殊挑战
直接从GitHub克隆OnnxRuntime仓库对国内开发者来说可能是个挑战。以下是几种可靠的替代方案。
2.1 使用镜像源
国内用户可以考虑从Gitee镜像克隆：
git clone --branch v1.12.1 --recursive https://gitee.com/mirrors/onnxruntime.git重要提示：--recursive参数必须加上，否则会缺少关键的子模块依赖。
2.2 子模块更新的问题
即使成功克隆了主仓库，子模块更新可能仍然会失败。这时可以手动更新：
cd onnxruntime git submodule sync git submodule update --init --recursive --jobs 8如果某些子模块仍然无法获取，可以尝试修改.gitmodules文件，将相关URL替换为镜像地址。
3. 编译配置：参数选择的艺术
OnnxRuntime的build.sh脚本提供了大量配置选项，选择不当会导致编译失败或性能问题。
3.1 基础编译命令解析
一个典型的编译命令如下：
./build.sh --skip_tests --config Release --build_shared_lib --parallel $(nproc)各参数含义：
--skip_tests：跳过测试编译，节省大量时间--config Release：生成优化后的发布版本--build_shared_lib：生成动态链接库而非静态库--parallel $(nproc)：使用所有CPU核心加速编译
3.2 CUDA支持的注意事项
如果需要CUDA支持，必须确保CUDA环境变量正确设置：
export CUDA_HOME=/usr/local/cuda-11.6 export CUDNN_HOME=/usr/local/cuda-11.6然后添加编译选项：
./build.sh --use_cuda --cuda_version=11.6 --cudnn_home=$CUDNN_HOME --cuda_home=$CUDA_HOME常见问题：
- CUDA版本不匹配：OnnxRuntime 1.12.1官方支持CUDA 11.6，使用其他版本需要自行承担风险
- cuDNN路径错误：确保
$CUDNN_HOME指向包含include和lib64目录的路径
4. 安装与验证：确保一切就绪
编译完成后，安装过程看似简单，但有几个关键点需要注意。
4.1 安装到系统目录
cd build/Linux/Release sudo make install默认安装路径是/usr/local，如果你想安装到自定义目录：
cmake -DCMAKE_INSTALL_PREFIX=/your/custom/path ..4.2 验证安装是否成功
创建一个简单的测试程序test_onnx.cpp：
#include <onnxruntime/core/session/onnxruntime_cxx_api.h> #include <iostream> int main() { Ort::Env env(ORT_LOGGING_LEVEL_WARNING, "test"); Ort::SessionOptions session_options; std::cout << "ONNX Runtime initialized successfully!" << std::endl; return 0; }编译并运行：
g++ -std=c++17 test_onnx.cpp -o test_onnx -lonnxruntime ./test_onnx如果看到成功消息，说明安装正确。如果遇到链接错误，检查/usr/local/lib是否在你的库路径中：
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH5. 高级技巧与性能优化
5.1 减少二进制体积
如果空间有限，可以移除不需要的Execution Provider：
./build.sh --disable_ml_ops --disable_contrib_ops --minimal_build5.2 调试符号与性能分析
对于开发环境，你可能需要保留调试符号：
./build.sh --config Debug --build_shared_lib或者同时保留优化和调试信息：
./build.sh --config RelWithDebInfo --build_shared_lib5.3 交叉编译注意事项
如果你需要为其他平台编译，比如ARM架构：
./build.sh --config Release --arm64 --parallel $(nproc)这需要提前安装交叉编译工具链：
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu6. 常见问题解决方案
6.1 "Could NOT find Protobuf"错误
这个问题通常发生在Protobuf版本冲突时。解决方案：
sudo apt remove libprotobuf-dev protobuf-compiler conda install -c conda-forge protobuf=3.20.1然后重新运行cmake生成步骤。
6.2 内存不足导致的编译失败
OnnxRuntime编译是内存密集型操作。如果遇到OOM错误，尝试：
./build.sh --parallel 2 # 减少并行编译任务数或者增加swap空间：
sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile6.3 Python绑定问题
即使你只需要C++库，构建系统仍可能尝试构建Python绑定。要完全禁用：
./build.sh --skip_tests --disable_pybind7. 生产环境部署建议
7.1 容器化部署
考虑使用Docker确保环境一致性：
FROM ubuntu:20.04 RUN apt update && apt install -y build-essential cmake python3.8 COPY onnxruntime /onnxruntime WORKDIR /onnxruntime RUN ./build.sh --skip_tests --config Release --build_shared_lib --parallel $(nproc) RUN cd build/Linux/Release && make install7.2 版本兼容性矩阵
不同OnnxRuntime版本对依赖的要求：
| OnnxRuntime版本 | CUDA支持 | Python要求 | CMake最低版本 |
|---|---|---|---|
| 1.10.0 | 11.4 | 3.6-3.8 | 3.18 |
| 1.12.1 | 11.6 | 3.6-3.9 | 3.20 |
| 1.13.1 | 11.7 | 3.7-3.10 | 3.22 |
7.3 性能调优技巧
启用OpenMP支持：
./build.sh --enable_openmp针对特定CPU架构优化：
./build.sh --cmake_extra_defines onnxruntime_USE_AVX2=ON使用MKL加速数学运算：
./build.sh --use_mklml
在实际项目中，我发现最耗时的部分往往是第一次编译时的依赖下载和配置。建议在持续集成系统中缓存~/.cache/onnxruntime目录，可以显著减少后续构建时间。