1. 为什么在 Windows 上要从源码编译 OpenCV很多人第一次接触 OpenCV都是直接去官网下载一个预编译好的 exe双击安装然后在 Visual Studio 里配一下包含目录和库目录就完事了。这个流程确实快十分钟能跑通一个读取图片的 Demo。但只要你稍微往深走一步比如想用SIFT、SURF这类被挪到 contrib 模块里的算法或者想启用 CUDA 加速、想用 Intel 的 IPP 加速库、想裁掉那些根本用不到的模块来减小体积预编译包就立刻不够用了。预编译包是官方按“最大公约数”配置出来的它默认不带 contrib不带 CUDA不带某些视频编解码后端你没法改。源码编译的本质是把“别人替你做的取舍”变成“你自己做的取舍”。你可以决定要不要 contrib、要不要 CUDA、要不要 Qt 做 HighGUI 后端、要不要开启OPENCV_ENABLE_NONFREE来用那些有专利历史的算法。代价就是你需要一套完整的工具链CMake 负责生成工程文件Visual Studio 负责编译OpenCV 源码提供原料。这套组合在 Windows 上是最稳的因为 CMake 对 VS 的支持非常成熟生成的.sln可以直接在 IDE 里打开、调试、断点比在 Linux 上敲命令行对新手友好得多。我这次编译的是 OpenCV 4.5.2这是一个 LTS 性质的版本稳定、资料多、和 contrib 的版本号对得上。下面我把整个流程拆开讲包括每一步为什么这么做、参数怎么选、以及我踩过的那些坑。如果你是完全没编译过的新手跟着走能跑通如果你编译过但总是失败可以重点看第 4 节和第 5 节那里是我认为最容易出问题的地方。2. 编译前的环境准备与版本匹配逻辑2.1 三件套的版本选择不是随便定的编译 OpenCV 需要三个东西CMake、Visual Studio、OpenCV 源码。这三者的版本之间存在隐性的兼容关系选错了会在配置阶段直接报错而且报错信息往往很含糊让人摸不着头脑。先说 Visual Studio。OpenCV 4.5.2 这个版本官方 CI 主要覆盖的是 VS2015、VS2017、VS2019。我用的是 VS2019社区版就够了不需要专业版。为什么不推荐 VS2022因为 4.5.2 发布的时候 VS2022 还没正式铺开CMake 里的一些编译器特性检测逻辑对 VS2022 的MSVC_VERSION判断可能不完整虽然多数情况下能编过但偶尔会在vcruntime相关的头文件上出问题。如果你手头只有 VS2022也能编但要有心理准备可能需要手动改一两个 CMake 判断。CMake 的版本建议在 3.16 到 3.20 之间。太老的 CMake 不认识 VS2019 的生成器名称太新的 CMake比如 3.25 以上对某些旧策略的默认行为改了可能在FindCUDA之类的模块上报 warning 甚至 error。我实测 3.18.4 和 3.19.8 都很稳。安装 CMake 的时候记得勾选“Add CMake to the system PATH”否则后面在命令行里敲cmake会提示找不到命令。OpenCV 源码有两个包要下主仓库opencv-4.5.2和 contrib 仓库opencv_contrib-4.5.2。这两个的版本号必须完全一致4.5.2 配 4.5.2不能一个 4.5.2 一个 4.5.3否则 contrib 里的模块会引用主仓库里不存在的符号编译到一半才报错非常浪费时间。下载渠道用官方的 GitHub Release 页面选 Source code (zip) 那个不要下成 Windows 的 exe 自解压包。2.2 目录结构要提前规划好我见过很多人把源码解压到“下载”文件夹里路径里带中文、带空格然后 CMake 配置各种失败。Windows 上编译 OpenCV路径里绝对不能有中文和空格这是铁律。我建议在某个盘根目录下建一个干净的文件夹比如D:\opencv_build然后这样组织D:\opencv_build\ ├── source\ │ ├── opencv-4.5.2\ │ └── opencv_contrib-4.5.2\ ├── build\ CMake 生成工程文件的地方 └── install\ 最终编译产物安装的地方把源码放在source下build目录留空给 CMake 用install目录留空给编译后的安装步骤用。这种“源码、构建、安装”三分离的做法是 CMake 社区的标准实践好处是构建失败时你可以直接把build目录删掉重来不会污染源码安装目录独立出来以后你想换一个 OpenCV 版本只要改一下环境变量指向新的 install 目录就行不用动源码。注意build目录和install目录都不要提前放任何文件让 CMake 和编译过程自己去创建。如果你之前编译失败过一定要把build目录整个删掉再重新配置CMake 的缓存文件CMakeCache.txt会记住上一次的错误配置不删干净会一直失败。2.3 可选依赖现在不装以后想加就得重编OpenCV 在配置阶段会去检测一堆可选依赖检测到了就启用对应功能检测不到就跳过。这里有个关键点这些依赖是编译时决定的不是运行时决定的。也就是说如果你编译的时候没装某个库编出来的 OpenCV 就永久缺少那个功能以后想加只能重新编译一遍。所以如果你有明确的需求最好在第一次编译前就把依赖装好。常见的可选依赖有这么几个。Intel IPP 和 IPP IWIntel 的加速库能显著提升图像处理速度OpenCV 官方提供预编译的 ippicv 包CMake 配置时会自动下载你只要保证网络能通就行。TBBIntel 的线程构建块用于并行加速装了之后cv::parallel_for_会走 TBB 后端比默认的并发实现效率高。Eigen线性代数库很多几何计算模块会用到纯头文件库解压到某个目录然后在 CMake 里指定EIGEN_INCLUDE_PATH即可。Qt如果你想要一个带按钮、滑块、能交互的 HighGUI 窗口而不是 OpenCV 自带的那个简陋窗口就需要 Qt配置项是WITH_QT。我的建议是第一次编译先别装这些用最简配置跑通一遍确认工具链没问题。跑通之后如果你确实需要某个功能再装依赖、删 build 目录、重新配置编译。这样能把“工具链问题”和“依赖问题”分开排查不然一堆报错混在一起根本不知道是哪个环节出的错。3. CMake 配置阶段每个关键选项背后的取舍3.1 用 GUI 还是命令行我为什么推荐 GUICMake 有两种用法命令行cmake -D...和图形界面cmake-gui。老手喜欢命令行因为可以写成脚本复用。但我强烈建议第一次编译 OpenCV 的人用cmake-gui原因很实际OpenCV 的配置项有几百个你不可能全部记住GUI 里可以搜索、可以看每个变量的当前值和类型配置完还能直观地看到哪些是红色新发现或未设置的变量。命令行模式下你敲错一个变量名CMake 不会报错它会默默创建一个同名的新变量然后你配置出来的结果和预期完全不一样排查起来很痛苦。打开cmake-gui之后第一行填源码目录指向D:\opencv_build\source\opencv-4.5.2第二行填构建目录指向D:\opencv_build\build。然后点 Configure会弹出一个对话框让你选生成器。这里选Visual Studio 16 2019下面的平台选x64。为什么选 x64 而不是 Win32因为现在 64 位是主流而且 x64 下能用的内存更大编译大型项目时不容易因为 32 位地址空间不足而失败。如果你有特殊需求必须编 32 位的选 Win32但要注意后面所有依赖也必须是 32 位的。3.2 第一次 Configure 之后要改哪些值第一次 Configure 会跑一两分钟它会去检测编译器、检测系统环境、下载 ippicv 等预编译包。跑完之后你会看到一大堆红色条目红色表示“这个变量是这次新出现的或者值变了”。你不需要改所有红色项只需要关注下面这几个关键的。BUILD_opencv_world这个选项决定要不要把所有模块合并成一个大的opencv_world452.dll。合并的好处是部署简单一个 dll 搞定不用管模块之间的依赖顺序坏处是体积大而且如果你只想用其中几个模块也会把整个 world 都链接进去。我个人的习惯是不勾选保持模块独立这样调试的时候能清楚看到每个功能来自哪个模块而且最终 install 出来的目录结构更清晰。如果你是要做产品发布、追求部署简单可以勾选。OPENCV_EXTRA_MODULES_PATH这是 contrib 模块的路径必须手动设置。点这一项右边的...按钮选择D:\opencv_build\source\opencv_contrib-4.5.2\modules。注意是选到modules这一层不是选到opencv_contrib-4.5.2根目录。选错了 CMake 会找不到任何 contrib 模块配置完你会发现xfeatures2d之类的模块根本没出现。OPENCV_ENABLE_NONFREE如果你要用 SIFT、SURF 这些算法必须勾选这一项。不勾的话xfeatures2d模块里的SIFT类虽然能编译出来但运行时会抛异常说“该功能不可用”。这个选项的名字叫 NONFREE是因为这些算法历史上涉及专利现在专利大多过期了但 OpenCV 出于谨慎还是把它放在这个开关后面。WITH_CUDA如果你有 NVIDIA 显卡并且装了 CUDA Toolkit可以勾选。但我要提醒一句CUDA 编译非常耗时而且对 CUDA 版本、显卡驱动、MSVC 版本三者之间的兼容性要求很严。我第一次编 CUDA 版的时候因为 CUDA 版本比 VS 支持的版本新了一点点CMake 直接报“unsupported MSVC version”。如果你只是做普通图像处理不需要 GPU 加速就别勾能省下大量编译时间。BUILD_EXAMPLES这个选项控制要不要编译示例代码。默认是不勾的。我建议勾上因为示例代码能帮你验证编译出来的库是否真的能用而且示例里有很多 API 的用法参考。代价是编译时间会增加一些但值得。CMAKE_INSTALL_PREFIX这是安装路径默认是C:\Program Files\opencv我建议改成D:\opencv_build\install。原因有两个一是Program Files目录需要管理员权限才能写入编译完执行 INSTALL 目标时可能因为权限失败二是放在自己的目录下以后想删想换都方便不会在系统盘留一堆东西。改完这些之后再点一次 Configure。这次红色条目会少很多。如果还有红色的通常是某些可选依赖没找到比如TBB_DIR、EIGEN_INCLUDE_PATH之类的你没装就不用管它们不影响编译。确认没有报错看下面的输出框只要不是 Error 就行Warning 可以忽略之后点 Generate。3.3 Generate 之后你得到了什么Generate 成功的话输出框最后会显示“Generating done”然后build目录里会出现OpenCV.sln这个解决方案文件。这个.sln就是 Visual Studio 的工程文件里面包含了所有模块的编译配置。你可以直接双击打开它也可以在 CMake GUI 里点“Open Project”按钮打开。打开.sln之后你会在解决方案资源管理器里看到几十个项目。这里有个关键操作把编译模式从 Debug 切到 Release。VS 默认是 Debug 模式Debug 模式下编译出来的库带大量调试信息体积大、运行慢而且和 Release 模式的库不能混用。如果你后面要用 Release 版的程序链接 OpenCV就必须用 Release 模式编译 OpenCV。我一般两个模式都编一遍Debug 用于自己调试Release 用于发布。但第一次编译先编 Release因为快。4. 编译与安装那些让人抓狂的报错和解决思路4.1 编译过程到底在做什么在 VS 里右键CMakeTargets下的ALL_BUILD项目选择“生成”。这就是开始编译了。编译过程会依次编译每个模块的源文件生成.obj然后链接成.lib和.dll。整个过程在普通四核机器上大概需要 20 到 40 分钟取决于你选了多少模块、开没开 CUDA。如果开了 CUDA时间可能翻倍甚至更多。编译的时候VS 的输出窗口会滚动大量信息。你不需要盯着看但要注意最后的结果。如果显示“生成: 成功 N 个失败 0 个跳过 0 个”那就是成功了。如果有失败会显示失败的项目名你需要往上翻找到具体的错误信息。这里我要强调一个很多人忽略的点编译顺序是有依赖的。opencv_core是最底层的模块几乎所有其他模块都依赖它。如果opencv_core编译失败后面所有模块都会跟着失败你会看到几十个失败项目但根源只有一个。所以看到大量失败时不要慌往上翻到第一个失败的项目那才是真正的问题所在。4.2 我遇到过的几个典型报错报错一fatal error C1083: 无法打开包括文件: opencv2/opencv_modules.hpp这个报错通常出现在编译 contrib 模块的时候。原因是opencv_modules.hpp这个文件是在配置阶段由 CMake 生成的它记录了哪些模块被启用了。如果这个文件没生成或者生成的位置不对contrib 模块就找不到它。解决办法是回到 CMake GUI确认OPENCV_EXTRA_MODULES_PATH设置正确然后删掉build目录重新 Configure Generate。不要试图手动去创建这个文件它里面的内容是根据你的配置动态生成的手写必错。报错二error LNK2019: 无法解析的外部符号链接错误通常是因为某个模块依赖的库没找到。比如opencv_videoio在 Windows 上默认会去链接mfplat.lib、mfreadwrite.lib这些系统库如果你的 Windows SDK 版本不对或者 VS 安装时没勾选对应的组件就会报这个错。解决办法是打开 VS Installer确认“Windows 10 SDK”这个组件装了而且版本不要太老。我用的 10.0.19041.0 没问题。报错三编译到opencv_dnn时卡住或者内存爆掉opencv_dnn模块的源文件很大编译时非常吃内存。如果你机器只有 8G 内存同时开着浏览器和其他程序可能会因为内存不足导致编译进程被系统杀掉表现就是 VS 突然卡死然后报一个莫名其妙的错误。解决办法是关掉其他占内存的程序或者单独编译opencv_dnn这个项目不要用ALL_BUILD一次性编所有。单独编译的方法是右键opencv_dnn项目选择“仅生成”。报错四CMake Error: The following variables are used in this project, but they are set to NOTFOUND这个错误发生在 Configure 阶段通常是某个可选依赖的路径没设置对。比如你勾了WITH_QT但没设置Qt5_DIRCMake 就会报这个错。解决办法是要么把依赖装好、路径设对要么把对应的WITH_选项取消勾选。不要留着WITH_QT勾选但路径空着那必然报错。4.3 编译成功后的 INSTALL 步骤ALL_BUILD编译成功只意味着.lib和.dll在build目录里生成了但它们还散落在各个子目录里没有组织成一个方便使用的结构。你需要再编译INSTALL项目它会把所有头文件、库文件、dll 复制到CMAKE_INSTALL_PREFIX指定的目录里形成标准的include、x64/vc16/lib、x64/vc16/bin结构。操作方法是在 VS 的解决方案资源管理器里找到CMakeTargets下的INSTALL项目右键选择“仅生成”。注意是“仅生成”不是“生成”因为 INSTALL 依赖于 ALL_BUILD 已经完成你不需要它再检查一遍依赖。生成完成后去D:\opencv_build\install看看应该能看到include文件夹和x64文件夹。x64\vc16\bin里是 dllx64\vc16\lib里是 lib。提示如果你后面要写程序用 OpenCV需要把install\x64\vc16\bin加到系统环境变量Path里否则运行程序时会提示找不到opencv_world452.dll或对应的模块 dll。加完环境变量要重启命令行或者重启 VS 才能生效。5. 在 Visual Studio 项目里正确引用编译好的 OpenCV5.1 手动配置包含目录和库目录新建一个空的 C 控制台项目然后打开项目属性。需要改三个地方。第一C/C-常规-附加包含目录加上D:\opencv_build\install\include。第二链接器-常规-附加库目录加上D:\opencv_build\install\x64\vc16\lib。第三链接器-输入-附加依赖项加上你需要用到的 lib 文件名。这里有个细节如果你编译时勾了BUILD_opencv_world那只需要加一个opencv_world452.lib。如果没勾就需要把用到的模块 lib 都加上比如opencv_core452.lib、opencv_imgproc452.lib、opencv_highgui452.lib、opencv_imgcodecs452.lib等等。漏加一个链接时就会报“无法解析的外部符号”而且报错信息里不会直接告诉你缺哪个 lib你得根据符号名去猜是哪个模块的。这也是我不推荐新手用 world 的原因之一——world 只有一个 lib不会漏。5.2 Debug 和 Release 的 lib 不能混用这是一个非常经典的坑。OpenCV 编译出来有两套 libopencv_core452.lib和opencv_core452d.lib后者带d后缀是 Debug 版。如果你的 VS 项目是 Debug 模式就必须链接带d的 lib如果是 Release 模式就必须链接不带d的。混用的话链接阶段可能不报错但运行时会崩溃而且崩溃位置往往在库内部堆栈信息很难看懂。我一般的做法是在项目属性里用宏来区分。在附加依赖项里这样写opencv_core452$(OpenCVDebugSuffix).lib然后在C/C-预处理器-预处理器定义里Debug 配置加OpenCVDebugSuffixdRelease 配置加OpenCVDebugSuffix空。这样切换配置时不用手动改 lib 名字。当然如果你嫌麻烦也可以直接为 Debug 和 Release 分别维护一份属性表用属性管理器来切换。5.3 一个最小验证程序配置好之后写一个最简单的程序验证一下#include opencv2/opencv.hpp #include iostream int main() { cv::Mat img cv::imread(test.jpg); if (img.empty()) { std::cout 无法读取图片 std::endl; return -1; } cv::imshow(窗口, img); cv::waitKey(0); std::cout OpenCV 版本: CV_VERSION std::endl; return 0; }把一张test.jpg放在项目工作目录下编译运行。如果能看到图片窗口并且控制台输出了版本号说明整个链路都通了。如果报错说找不到 dll检查环境变量Path如果报错说无法解析的外部符号检查附加依赖项如果imread返回空检查图片路径和格式支持。6. 编译参数调优与体积裁剪的实战经验6.1 裁掉不需要的模块能省多少空间OpenCV 4.5.2 全模块编译出来install目录大概有 2 到 3 个 G。如果你只做基础的图像读取、显示、处理很多模块根本用不到。比如opencv_dnn是深度学习推理模块如果你不做神经网络可以关掉opencv_stitching是图像拼接用不到也可以关opencv_videostab是视频防抖同理。关掉的方法是在 CMake GUI 里把对应的BUILD_opencv_xxx取消勾选。我做过一个对比只保留core、imgproc、imgcodecs、highgui、videoio这五个模块编译出来的install目录只有 200 多 M编译时间也从 40 分钟降到 10 分钟左右。对于只需要基础功能的项目这个裁剪非常划算。但要注意关掉模块之后如果你后面发现某个功能需要用到被关掉的模块就得重新编译所以裁剪之前最好想清楚自己的需求边界。6.2 开启 IPP 和 TBB 带来的性能差异IPP 是 Intel 的加速库OpenCV 在配置阶段会自动下载ippicv包。开启 IPP 后很多基础操作比如cv::resize、cv::cvtColor、矩阵运算等会走 IPP 的优化实现速度提升在 Intel CPU 上非常明显。我实测一个 4K 图像的 resize 操作开 IPP 比不开快大约 30% 到 50%。这个提升是免费的只要网络能下载到 ippicv 包就行建议都开着。TBB 是并行加速库影响的是cv::parallel_for_的底层实现。OpenCV 默认用一套自己的并发机制在 Windows 上基于Concurrency Runtime。装了 TBB 之后并行循环的调度效率会更高尤其是在多核 CPU 上做逐像素处理时。但 TBB 需要额外安装而且版本要和 OpenCV 兼容。如果你不想折腾默认的并发机制也够用性能差距没有 IPP 那么明显。6.3 编译时间太长怎么办编译 OpenCV 是个体力活尤其是全模块加 contrib。如果你觉得 40 分钟太久有几个办法可以加速。第一用ALL_BUILD的时候在 VS 里把“并行项目生成”打开工具 - 选项 - 项目和解决方案 - 生成并运行 - 最大并行项目生成数设成你 CPU 的核心数。第二关掉不需要的模块减少编译量。第三如果你只是改了一两个文件想重新编译不要用ALL_BUILD只编译那个模块的项目然后重新 INSTALL 即可。第四把build目录放在 SSD 上机械硬盘的随机读写会严重拖慢编译速度。注意并行编译虽然快但内存占用也会成倍增加。如果你内存小于 16G并行数不要设太高否则容易触发内存不足导致编译失败。我 16G 内存的机器上并行数设 4 比较稳设 8 就会偶尔失败。7. 从源码编译这件事我踩过的最深的三个坑第一个坑是路径里的空格。我一开始把源码放在C:\Users\My Name\Downloads\opencv-4.5.2用户名里带空格CMake 配置到一半就报了一堆莫名其妙的路径错误。后来把源码移到D:\opencv_build\source才解决。Windows 上很多构建工具对空格路径的处理都不完善CMake 虽然号称支持但 OpenCV 的某些自定义 CMake 脚本里用了没加引号的路径变量遇到空格就断开了。所以路径里不要有空格、中文、特殊字符这是最省事的做法。第二个坑是 contrib 版本不匹配。我有一次主仓库下了 4.5.2contrib 顺手下了最新的 4.x 分支结果编译到xfeatures2d时报了一堆“找不到基类成员”的错误。原因是 contrib 的新代码引用了主仓库新版本才有的 API而 4.5.2 里没有。后来把 contrib 换成 4.5.2 对应的 tag 才编过。所以记住主仓库和 contrib 的版本号必须严格一致差一个小版本都可能出问题。第三个坑是 Debug 和 Release 混编。我曾经在一个 Release 项目里链接了 Debug 版的 OpenCV lib编译链接都通过了但一运行就崩溃崩溃位置在opencv_core452d.dll里面。用调试器跟进去发现是内存分配和释放跨了不同的 CRT 运行时Debug 版和 Release 版的堆管理不兼容。这个问题的隐蔽性在于它不报链接错误只在运行时崩而且崩溃点看起来和你的代码无关。解决办法就是严格区分 Debug 和 Release用属性表或者宏来管理 lib 名字不要手动混用。8. 编译完成之后怎么管理多个 OpenCV 版本如果你只编一个版本那install目录放着不动就行。但如果你同时需要 4.5.2 和另一个版本比如 4.8.0就需要做版本管理。我的做法是在D:\opencv_build\install下按版本建子目录比如install\4.5.2和install\4.8.0。然后在 VS 项目里用属性表来切换每个属性表对应一个版本包含目录、库目录、依赖项都写死。这样切换版本只需要在属性管理器里换一个属性表不用手动改一堆路径。环境变量Path里也可以只加当前正在用的那个版本的bin目录。如果你需要频繁切换可以写两个批处理文件一个设置 4.5.2 的环境一个设置 4.8.0 的用的时候运行对应的批处理打开命令行。这样能避免 dll 版本冲突——如果你Path里同时有两个版本的bin程序加载 dll 时可能加载到错误版本导致行为异常甚至崩溃。另外编译出来的install目录是可以打包备份的。如果你在另一台机器上需要同样的 OpenCV直接把install目录拷过去然后在新机器上设置好环境变量和 VS 的包含/库路径就行不需要重新编译。前提是新机器的 VS 版本和编译时用的 VS 版本一致因为vc16这个目录名对应的是 VS2019 的工具集VS2017 是vc15VS2022 是vc17工具集不兼容的话链接会出问题。9. 关于 OpenCV 4.5.2 源码编译的一些个人体会编译 OpenCV 这件事第一次做会觉得步骤繁琐、报错吓人但做过一遍之后就会发现它其实是个很线性的流程准备环境、配置 CMake、编译、安装、引用。每个环节的坑我都在这篇里列出来了你照着走大概率能一次成功。我自己的经验是第一次编译不要贪多不要一上来就开 CUDA、开 Qt、开所有 contrib 模块先用最简配置跑通确认工具链没问题然后再逐步加需求。这样出问题的时候你能快速定位是哪个新加的选项导致的。还有一点编译过程中产生的build目录会非常大可能有好几个 G。如果你编译成功并且 INSTALL 完成build目录其实可以删掉只保留install目录和源码。但我不建议马上删因为万一后面发现某个模块有问题需要重新编译留着build目录可以增量编译比重头来快得多。等确认一切正常、并且备份了install目录之后再删build也不迟。最后说一个细节OpenCV 的 CMake 配置里有一个OPENCV_GENERATE_SETUPVARS选项默认是开的。它会在install目录下生成一个OpenCVConfig.cmake和setup_vars_opencv4.cmd。前者是给 CMake 项目用的后者是给命令行用的。如果你用 CMake 构建自己的项目可以直接find_package(OpenCV REQUIRED)它会自动读取OpenCVConfig.cmake来找到头文件和库比手动配路径方便得多。这个文件的存在也是源码编译相对于预编译包的一个优势——预编译包虽然也有但源码编译的版本信息更准确不会出现“找不到某个模块”的假阴性。
