C++部署YOLO模型：基于CMake、OpenCV与ONNX Runtime的完整工程化指南

C++部署YOLOONNX RuntimeOpenCV DNN

于 2026-08-03 03:57:59 修改

·本内容遵循CC 4.0 BY-SA版权协议

在实际项目中，将前沿的深度学习模型，如 YOLO 系列，集成到 C++ 应用程序中，是计算机视觉工程师和 C++ 开发者面临的核心挑战。这不仅仅是调用一个 Python 脚本那么简单，它涉及到模型格式转换、跨平台构建、高性能推理引擎选择以及生产环境部署等一系列工程化问题。许多开发者卡在环境配置、库版本冲突或构建失败上，导致无法将训练好的模型真正落地。

本文将围绕“C++ 部署 YOLO 模型”这一核心目标，提供一个从零开始的完整工程化教程。我们将采用 CMake 作为项目构建工具，使用 OpenCV DNN 模块进行图像预处理和后处理，并集成 ONNX Runtime 作为高性能推理后端。这套组合兼顾了开发便利性、部署灵活性和运行效率，是工业级 C++ 视觉应用的主流选择之一。无论你是希望将 Python 训练的 YOLO 模型迁移到 C++ 环境，还是为嵌入式设备（如 RK3588、K230）或服务器端构建高性能推理服务，本文的步骤和代码都能提供一个坚实的起点。

通过本教程，你将学会如何搭建一个跨平台的 C++ 深度学习推理项目，理解 CMake 如何管理复杂的第三方库依赖，掌握使用 OpenCV DNN 处理图像以及用 ONNX Runtime 执行模型推理的完整流程。我们不仅会提供可运行的代码，更会解释每一步背后的设计考量、常见陷阱及其排查方法。

1. 环境准备与工具链选择

在开始编码之前，搭建一个稳定、可复现的构建环境至关重要。C++ 项目的环境配置往往比 Python 更复杂，因为涉及编译器、库的版本和链接问题。

1.1 核心工具与库版本说明

我们选择以下工具链，它们都是开源、跨平台且被广泛验证的：

编译器: MSVC (Windows) 或 GCC (Linux/macOS)。确保支持 C++11 及以上标准。
构建系统: CMake (>= 3.16)。它是管理 C++ 项目依赖和跨平台构建的事实标准。
核心库:
- OpenCV (>= 4.5.0): 我们主要使用其 dnn 模块进行图像读取、预处理（缩放、归一化）和后处理（非极大抑制，NMS）。建议编译时开启 OPENCV_DNN_CUDA 以支持 GPU 推理（如果硬件支持）。
- ONNX Runtime (>= 1.14.0): 微软开源的高性能推理引擎。我们将下载其预编译的 C++ 库。它支持 CPU、CUDA、TensorRT 等多种执行提供程序（Execution Provider）。
模型格式: ONNX。这是连接不同训练框架（PyTorch, TensorFlow等）和推理引擎的桥梁。你需要先将训练好的 YOLO 模型（如 .pt 文件）转换为 .onnx 格式。

下表列出了关键组件的推荐版本和获取方式：

组件	推荐版本	获取方式	备注
CMake	>= 3.16	官网下载安装包或使用包管理器 (`apt-get`, `brew`)	确保 `cmake` 命令在终端可用。
OpenCV	4.8.0	从 GitHub 源码编译，或使用预编译包（如 `vcpkg`, `apt`）。	源码编译能更好地控制模块和优化选项。
ONNX Runtime	1.16.3	从 GitHub Release 页面下载对应平台和配置的预编译包。	选择与你的系统（Win/Linux）、架构（x64/arm64）和运行时（MSVC/gcc）匹配的版本。
YOLO 模型	v5, v8 等	从 Ultralytics 官方仓库获取预训练权重或使用自己训练的模型。	最终需要转换为 `.onnx` 格式。

注意：版本兼容性是 C++ 项目最大的“坑”之一。强烈建议在项目初期就锁定这些库的版本，并记录在 README 或 CMakeLists.txt 中，以确保团队其他成员和构建服务器环境一致。

1.2 项目目录结构规划

一个清晰的项目结构能极大提升代码的可维护性和构建的可靠性。在开始前，建议创建如下目录：

TEXT

yolo_cpp_deployment/

├── CMakeLists.txt # 项目根 CMake 配置文件

├── cmake/ # 放置查找第三方库的 CMake 脚本

│ └── FindONNXRuntime.cmake

├── src/ # 项目源代码

│ ├── main.cpp # 程序入口

│ ├── detector.h # 检测器类声明

│ ├── detector.cpp # 检测器类实现

│ └── utils.h # 工具函数（如画框、NMS）

├── models/ # 存放模型文件

│ └── yolov8n.onnx

├── data/ # 存放测试图片/视频

│ └── test.jpg

├── 3rdparty/ # 存放第三方库（可选）

│ ├── opencv/

│ └── onnxruntime/

└── build/ # 构建输出目录（不应提交到版本库）

3rdparty 目录用于存放自行下载的 OpenCV 和 ONNX Runtime 库，这种方式适合离线环境或需要固定特定版本的项目。如果使用系统包管理器安装，则不需要此目录。

2. 使用 CMake 配置项目与依赖

CMake 的核心是 CMakeLists.txt 文件，它定义了项目的构建规则。我们将编写一个能够自动查找 OpenCV 和 ONNX Runtime 的 CMake 脚本。

2.1 编写根目录的 CMakeLists.txt

在项目根目录创建 CMakeLists.txt，内容如下：

CMAKE

cmake_minimum_required(VERSION 3.16)

project(YOLOCPPDeployment LANGUAGES CXX)

# 设置 C++ 标准

set(CMAKE_CXX_STANDARD 11)

set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(CMAKE_CXX_EXTENSIONS OFF)

# 设置构建类型（Debug/Release），如果未指定则默认为 Debug

if(NOT CMAKE_BUILD_TYPE)

set(CMAKE_BUILD_TYPE “Debug”)

endif()

# 将 cmake 模块路径添加到搜索路径，以便找到我们自定义的 FindXXX.cmake

list(APPEND CMAKE_MODULE_PATH “${PROJECT_SOURCE_DIR}/cmake”)

# 查找 OpenCV 库

find_package(OpenCV REQUIRED)

if(OpenCV_FOUND)

message(STATUS “Found OpenCV: ${OpenCV_DIR}”)

include_directories(${OpenCV_INCLUDE_DIRS})

else()

message(FATAL_ERROR “OpenCV not found. Please install it or set OpenCV_DIR.”)

endif()

# 查找 ONNX Runtime 库

find_package(ONNXRuntime REQUIRED)

if(ONNXRuntime_FOUND)

message(STATUS “Found ONNX Runtime: ${ONNXRuntime_DIR}”)

include_directories(${ONNXRuntime_INCLUDE_DIRS})

else()

message(FATAL_ERROR “ONNX Runtime not found.”)

endif()

# 添加可执行文件目标

add_executable(yolo_inference src/main.cpp src/detector.cpp src/utils.h)

# 链接库

target_link_libraries(yolo_inference

${OpenCV_LIBS}

${ONNXRuntime_LIBRARIES}

)

# 在 Debug 和 Release 模式下设置不同的输出目录，保持整洁

set_target_properties(yolo_inference PROPERTIES

RUNTIME_OUTPUT_DIRECTORY “${CMAKE_BINARY_DIR}/bin/$<CONFIG>”

)

这个脚本做了几件关键事情：

声明项目并强制使用 C++11。
通过 find_package 查找 OpenCV。如果 OpenCV 安装在非标准路径，你需要在运行 CMake 时通过 -DOpenCV_DIR=/path/to/opencv/build 指定。
通过自定义模块查找 ONNX Runtime。
将源文件编译成名为 yolo_inference 的可执行文件。
将找到的库链接到可执行文件。