OpenCV 安装与部署：源码 CMake 编译与 ARM 交叉编译

安装与部署：源码 CMake 编译与 ARM 交叉编译

端侧部署基本不用发行版自带的 OpenCV 包，因为那些包默认开了大量模块，体积和依赖都不合适。标准做法是源码编译并精确控制开关。

1. 拉取源码。主仓库是 opencv/opencv，需要 contrib 模块时再拉 opencv/opencv_contrib，两者版本必须一致。
2. 用 CMake 配置构建目录，通过 BUILD_LIST 限定模块、通过 WITH_* 关闭不需要的第三方依赖。
3. 主机上先编一遍验证配置无误，再换交叉编译工具链文件编到目标架构。
4. 用 cmake --install 安装到独立前缀目录，打包时只带需要的头文件与库。
5. 在目标板上用一个小程序验证 imread 与 dnn 推理都能跑通，再接入正式工程。

# 1. 拉源码（主仓库 + contrib，版本保持一致）
git clone --depth 1 -b <tag> https://github.com/opencv/opencv.git
git clone --depth 1 -b <tag> https://github.com/opencv/opencv_contrib.git

# 2. 主机端精简构建：只留 core / imgproc / imgcodecs / dnn
cmake -S opencv -B build-host \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=./install-host \
  -DOPENCV_EXTRA_MODULES_PATH=./opencv_contrib/modules \
  -DBUILD_LIST=core,imgproc,imgcodecs,dnn \
  -DBUILD_SHARED_LIBS=OFF \
  -DBUILD_TESTS=OFF -DBUILD_PERF_TESTS=OFF -DBUILD_EXAMPLES=OFF \
  -DBUILD_opencv_apps=OFF -DBUILD_JAVA=OFF -DBUILD_opencv_python3=OFF \
  -DWITH_OPENCL=OFF -DWITH_TBB=OFF -DWITH_ITT=OFF -DWITH_IPP=OFF \
  -DWITH_PROTOBUF=ON -DWITH_GTK=OFF -DWITH_FFMPEG=OFF
cmake --build build-host -j"$(nproc)"
cmake --install build-host

交叉编译到 ARM 板时，OpenCV 源码里已经带了可用的工具链文件，直接引用即可，省去自己写 CMAKE_TOOLCHAIN_FILE：

# 3. 交叉编译到 aarch64 Linux 板（工具链文件由 OpenCV 提供）
cmake -S opencv -B build-arm64 \
  -DCMAKE_TOOLCHAIN_FILE=./opencv/platforms/linux/aarch64-gnu.toolchain.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=./install-arm64 \
  -DBUILD_LIST=core,imgproc,imgcodecs,dnn \
  -DBUILD_SHARED_LIBS=OFF \
  -DBUILD_TESTS=OFF -DBUILD_PERF_TESTS=OFF -DBUILD_EXAMPLES=OFF \
  -DWITH_OPENCL=OFF -DWITH_TBB=OFF -DWITH_GTK=OFF -DWITH_FFMPEG=OFF
cmake --build build-arm64 -j"$(nproc)"
cmake --install build-arm64

# 32 位 ARM（Cortex-A7/A9 一类）改用：
# -DCMAKE_TOOLCHAIN_FILE=./opencv/platforms/linux/arm-gnueabi.toolchain.cmake

需要特别注意：上面命令里的 <tag> 请替换成你要用的具体版本标签，不同版本支持的模块名、第三方依赖与 CMake 选项会有差异，拿不准的开关一律以官方文档为准。工具链文件名也可能随版本调整，若路径不存在，去 opencv/platforms/linux/ 目录下看实际提供了哪些文件。

常见的编译报错与排查：

• CMake Error: could not find protobuf：dnn 模块依赖 protobuf，交叉编译时常需为目标架构准备 protobuf 或改用无 protobuf 的构建路径，构建日志里会明确写出缺失项，按提示补依赖即可。
• 链接阶段报未定义符号（如 jpeg、png、zlib 相关）：imgcodecs 的编解码后端未正确找到，静态链接时最容易出现。确认第三方库确实是目标架构版本，而不是主机版本。
• imread 运行时返回空 Mat：编解码后端没编进去，或者路径与实际文件不匹配；用 cv::haveImageReader / cv::haveImageWriter 判断当前构建是否支持目标格式。
• 交叉编译通过但板子上跑起来崩溃：常见于工具链的浮点 ABI 与系统不匹配（软浮点 / 硬浮点混用），核对工具链与根文件系统的 ABI 设置。