手把手教你编译 OpenCV 4 + Contrib：VS2017 实战指南

一、编译前的深度准备#

编译 OpenCV 及其扩展库（Contrib）需要严谨的目录结构，建议按下图方式组织，以防配置路径时出错：

源码下载：
OpenCV 4.x: GitHub 仓库
OpenCV-Contrib 4.x: GitHub 仓库（版本必须与源码完全一致）
工具安装：
VS2017：确保勾选了“使用 C++ 的桌面开发”。
CMake 3.13+：建议使用 GUI 版本，直观易操作。

二、 CMake 配置：决定成败的关键#

这是最容易报错的环节。请按照以下步骤精准操作：

1. 指定路径与初次 Configure#

Where is the source code: 选择 OpenCV 源码所在目录。
Where to build the binaries: 选择你创建的空 build 文件夹。
点击 Configure，弹窗中选择 Visual Studio 15 2017 Win64。

2. 引入 Contrib 扩展包#

在中间的搜索框中找到以下项并修改：

OPENCV_EXTRA_MODULES_PATH：填入 opencv_contrib-4.x/modules 的绝对路径。
OPENCV_ENABLE_NONFREE：务必勾选。这决定了你是否能使用 SIFT 等受专利保护的算法。
BUILD_opencv_world：建议勾选。它会将所有模块打包成一个 opencv_world4xx.lib，极大简化后续在 VS 中的配置工作。

🔥 避坑指南： > 第一次 Configure 后，CMake 会尝试下载 ippicv 等文件。由于网络原因经常失败（红字报错）。 解决办法： 查看 build/CMakeDownloadLog.txt，手动下载缺失文件并放入相应文件夹，或使用科学上网工具。

3. 生成工程#

点击 Configure 直到所有红项消失，最后点击 Generate，再点击 Open Project 进入 VS2017。

三、 Visual Studio 编译：最后的冲刺#

进入 VS2017 后，我们需要完成“批生成”。

切换配置：在上方工具栏确认当前是 x64。
批生成 (Batch Build)：

依次点击菜单：生成 -> 批生成。
找到 INSTALL 项目，勾选其 Debug 和 Release 两个版本的复选框。
点击生成。

结果产出：编译完成后，所有的库文件、头文件都会集中在 build/install 文件夹下。这是我们唯一需要保留的文件夹。

四、开发环境配置#

编译完成后，你的 OpenCV 库还不能直接使用，需要告诉系统在哪里找到它。

1. 系统环境变量#

将以下路径添加到系统变量的 Path 中： D:\opencv\build\install\x64\vc15\bin

2. VS2017 项目属性配置#

在你的 VS 项目中，右键项目属性进行如下配置：

包含目录 (Include)：...\install\include 和 ...\install\include\opencv2
库目录 (Library)：...\install\x64\vc15\lib
链接器输入 (Linker)：
Debug 模式：添加 opencv_world400d.lib
Release 模式：添加 opencv_world400.lib

五、总结与验证#

编译完成后，建议运行以下代码进行测试：

1
#include <opencv2/opencv.hpp>
2
#include <opencv2/xfeatures2d.hpp> // 只有配置了 contrib 才能调用此头文件
3

4
int main() {
5
    cv::Mat img = cv::imread("test.jpg");
6
    auto sift = cv::xfeatures2d::SIFT::create(); // 测试非免费模块
7
    // ... 后续代码
8
    return 0;
9
}

通过源码编译，你不仅可以自定义安装所需的模块，还能针对自己的硬件优化性能。虽然过程繁琐，但它是深入研究 OpenCV 的基石。

一、 编译前的深度准备#