OpenCV 安装与构建完整指南

克隆存储库

要克隆存储库，请在控制台中运行以下命令（git）：

git clone https://github.com/opencv/opencv
cd opencv
git checkout <version_tag>

# 可选
git clone https://github.com/opencv/opencv_contrib
cd opencv_contrib
git checkout <version_tag>

# 可选
git clone https://github.com/opencv/opencv_extra
cd opencv_extra
git checkout <version_tag>

注意：如果要使用多个存储库构建软件，请确保所有组件彼此兼容。对于 OpenCV，这意味着 opencv 和 opencv_contrib 存储库必须在同一标记下签出，或者所有快照存档都从同一版本下载。

在选择要下载的版本时，请考虑您的目标平台和开发工具版本，最新版本的 OpenCV 可能会在非常旧的编译器中出现构建问题，反之亦然。我们建议使用最新版本和新的操作系统/编译器组合。

步骤 2：配置

在此步骤中，CMake 将验证所有必要的工具和依赖项是否可用且与库兼容，并将为所选生成系统生成中间文件。它可以是 Makefile、IDE 项目和解决方案等。通常，此步骤在新创建的构建目录中执行：

cmake -G "Unix Makefiles" ..

注意：cmake-gui 应用程序允许使用图形用户界面查看和修改可用选项。有关详细信息，请参阅 CMake 官方文档。

步骤 3：构建

在构建过程中，源文件被编译为目标文件，这些文件链接在一起或以其他方式组合到库和应用程序中。可以使用通用命令运行此步骤：

cmake --build . --config Release

或者直接调用底层构建系统：

make -j$(nproc)

步骤 4：安装

在安装过程中，构建目录中的构建结果和其他文件将被复制到安装位置。默认安装位置在 UNIX 和 Windows 上不同。可以在配置步骤中通过设置 CMAKE_INSTALL_PREFIX 选项更改此位置。若要执行安装，请运行以下命令：

cmake --build . --target install

注意：此步骤是可选的，OpenCV 可以直接从构建目录使用。如果安装根目录是受保护的系统目录，则必须使用超级用户或管理员权限（例如 sudo cmake ...）。

三、构建插件

通过将部分代码提取到动态加载的插件中，可以解耦一些 OpenCV 依赖项并使其成为可选的。它有助于生成自适应二进制发行版，这些发行版可以在依赖性较低的系统上运行，并且只需安装缺少的库即可扩展功能。目前，core、videoio 和 highgui 模块的一些依赖项都支持这种机制。

在某些情况下，可以通过设置诸如 VIDEOIO_PLUGIN_LIST 或 HIGHGUI_PLUGIN_LIST 之类的选项来与 OpenCV 一起构建插件。在其他情况下，插件应该在它们自己的构建过程中单独构建。

注意：建议使用与 OpenCV 构建兼容的编译器、配置和构建选项，否则生成的库可能会拒绝加载或导致其他运行时问题。请注意，由于 OpenCV 和相应的第三方库之间存在额外的障碍，当动态加载后端时，某些功能可能会受到限制或工作速度变慢。

构建过程类似于主 OpenCV 构建，但您必须使用位于相应子目录中的特殊 CMake 项目。为插件使用名称前缀非常重要，以便加载器能够找到它们。下表列出了可能的前缀和项目位置：

示例：TBB 检测的设置环境，例如：

export TBB_DIR=/path/to/tbb
cmake -G "Unix Makefiles" \
  -DOPENCV_PLUGIN_NAME=opencv_core_tbb_<suffix> \
  -DOPENCV_PLUGIN_DESTINATION=<target_folder> \
  -DCMAKE_BUILD_TYPE=<configuration> \
  /modules/core/misc/plugins/parallel_tbb

cmake --build . --config <configuration>

注意：在 Windows 上，插件必须与现有的 OpenCV 版本链接。将环境变量或 CMake 变量设置为包含 OpenCVConfig.cmake 文件的目录，它可以是 OpenCV 构建目录或您执行安装的位置中的某个路径。

四、验证安装

构建完成后，建议验证 OpenCV 是否正确安装。

1. C++ 验证

编写一个简单的测试程序：

#include <opencv2/opencv.hpp>
#include <iostream>

int main() {
    std::cout << "OpenCV Version: " << CV_VERSION << std::endl;
    return 0;
}

编译并运行，确认输出版本号无误。

2. Python 验证

如果您安装了 Python 绑定，可以运行以下脚本：

import cv2
print(cv2.__version__)

若输出版本号且无报错，则安装成功。

五、常见问题排查

1. 权限不足

如果在安装时报错 Permission denied，请尝试使用 sudo 提升权限，或在配置阶段指定用户可写的安装路径。

2. 依赖缺失

构建过程中若提示缺少依赖库（如 FFmpeg, GTK, TBB），请检查系统包管理器是否已安装对应开发包（如 libxxx-dev 或 libxxx-devel）。

3. 链接错误

在链接阶段出现 undefined reference 错误，通常是因为未正确链接 OpenCV 库。请确保 CMakeLists.txt 中使用了 find_package(OpenCV REQUIRED) 并链接了 opencv_core 等必要模块。

4. Python 环境冲突

在 Python 环境中安装 OpenCV 时，若遇到版本冲突，建议使用虚拟环境（venv 或 conda env）隔离依赖。

六、总结

本文详细介绍了 OpenCV 的多种安装方式及源码构建流程。无论是使用预构建包还是自行编译，理解构建原理和依赖关系都能帮助您更灵活地部署 OpenCV。对于高级应用，掌握插件机制和动态加载能力将进一步增强系统的可扩展性。