1. 为什么还要折腾老版本OpenCV1.1 一个绕不开的现实场景你可能觉得奇怪OpenCV都更新到4.x后期版本了为什么还要回头折腾4.5.1我当初接到这个需求的时候也是同样的反应。但实际情况是很多工业视觉项目、教学课程体系、以及一些已经进入维护期的产品代码就是锁死在OpenCV 4.5.1这个版本上的。原因很简单API稳定、依赖链清晰、社区资料丰富而且大量第三方算法库比如某些特定的contrib模块、某些标定工具在这个版本上验证得最充分。更关键的是Visual Studio 2019搭配OpenCV 4.5.1这个组合在Windows 10上的兼容性经过了大量实际项目的检验。你如果直接上最新版反而可能遇到某些contrib模块编译不过、或者某些老代码调用方式被废弃的问题。所以不是我们不想用新版而是项目约束摆在那里稳定压倒一切。这篇文章要解决的问题非常具体在Win10环境下用CMake-GUI这个图形化工具从源码编译出一套专门给VS2019使用的OpenCV 4.5.1库。注意是从源码编译不是下载预编译包。为什么要自己编译因为预编译包通常只包含主模块contrib扩展模块、以及一些需要特定开关比如CUDA、OpenCL、IPP的功能必须自己动手。而且自己编译出来的库和你本机的VS2019版本、Windows SDK版本完全匹配后续调试时符号文件也能对得上排查问题方便得多。适合谁看如果你是一个需要在Windows上做C视觉开发的工程师手头项目指定了OpenCV 4.5.1和VS2019并且你希望把contrib模块也编进去那这篇内容就是为你准备的。哪怕你之前没用过CMake-GUI跟着走也能搞定。1.2 编译方案的核心思路整个流程的核心逻辑其实就三步准备源码和依赖、用CMake-GUI配置生成VS2019解决方案、在VS2019里编译并安装。听起来简单但每一步都有坑。为什么选CMake-GUI而不是命令行因为对于Windows上的C开发者来说图形界面能直观地看到所有配置项勾选、搜索、修改都很方便。尤其是OpenCV有上千个CMake选项命令行敲参数容易漏GUI里可以反复调整、反复Configure直到没有红色报错为止。而且CMake-GUI生成的缓存可以保存下次重新编译不用从头再来。为什么强调“用于VS2019”因为CMake在生成阶段需要指定Generator。如果你选错了Generator比如选了VS2022或者MinGW生成的解决方案文件在VS2019里打不开或者编译出来的库和你的项目链接不上。所以从Configure的第一步就要把Generator锁定为“Visual Studio 16 2019”并且平台选x64现在基本没人用32位了。还有一个关键决策动态库还是静态库。OpenCV默认编译成动态库DLL这样多个项目共用一份运行时磁盘占用小。但如果你希望最终exe拷到别的机器上不用带一堆DLL那就得编静态库。静态库的编译配置更麻烦需要把所有依赖比如libjpeg、libpng、zlib也静态链接进去。我个人的建议是第一次编译先走动态库把流程跑通确认contrib模块能用然后再考虑静态库的事。本文也以动态库为主线静态库的差异点我会在对应位置标注。2. 动手前的环境准备与工具选型2.1 软件清单与版本匹配在开始之前你需要把下面这些东西准备好。我列了一个表把每个工具的作用和版本要求说清楚工具推荐版本作用注意事项Visual Studio 201916.x 任意版本提供C编译器和IDE必须安装“使用C的桌面开发”工作负载CMake3.20以上生成VS解决方案安装时勾选“Add to PATH”CMake-GUI随CMake一起安装图形化配置界面开始菜单里搜“cmake-gui”OpenCV源码4.5.1主库源代码从官方发布页下载zip包OpenCV contrib源码4.5.1扩展模块源代码版本号必须和主库完全一致Python3.7-3.9部分模块的构建依赖安装时勾选“Add to PATH”7-Zip或WinRAR任意解压源码包无这里重点说几个容易出问题的地方。VS2019的工作负载如果你只装了VS2019但没装C桌面开发组件CMake在Configure时会报“找不到C编译器”。检查方法是打开VS2019 Installer看“使用C的桌面开发”是否打勾。Python版本OpenCV的某些模块比如python bindings需要Python但如果你不需要Python接口可以在CMake里把BUILD_opencv_python3关掉。不过为了省事建议还是装一个Python 3.8勾选添加到PATH这样CMake能自动找到。源码版本一致性OpenCV主库和contrib库的版本号必须严格一致。4.5.1的主库配4.5.1的contrib不能混用4.5.0或4.6.0。下载的时候注意看文件名主库是opencv-4.5.1.zipcontrib是opencv_contrib-4.5.1.zip。解压后放在同一个父目录下比如D:\opencv_build\里面有两个文件夹opencv-4.5.1和opencv_contrib-4.5.1。2.2 目录结构规划与磁盘空间我见过太多人把源码解压到桌面或者C盘用户目录下结果编译到一半磁盘满了或者路径里有中文和空格导致CMake报错。所以这一步必须提前规划好。推荐的结构是这样的D:\opencv_build\ ├── opencv-4.5.1\ 主库源码 ├── opencv_contrib-4.5.1\ 扩展模块源码 ├── build\ CMake生成目录空文件夹 └── install\ 编译后的安装目录空文件夹为什么要把build和install单独分出来因为CMake的生成过程会产生大量中间文件如果和源码混在一起清理起来很麻烦。而且install目录是最终要链接到VS项目里的单独放方便管理。磁盘空间完整编译OpenCV 4.5.1含contrib、含测试大约需要15-20GB的中间文件空间最终install目录大约2-3GB。所以D盘至少留30GB空闲。注意整个路径中不要出现中文、空格、特殊符号。比如“D:\我的项目\opencv”这种路径CMake在生成VS解决方案时可能因为编码问题失败。用纯英文、下划线、数字最稳妥。2.3 环境变量与命令行验证在打开CMake-GUI之前先做两个验证。第一打开命令提示符cmd输入cmake --version应该输出CMake的版本号。如果提示“不是内部或外部命令”说明CMake没加到PATH里需要手动加或者重新安装。第二输入python --version确认Python能正常调用。这两个命令能跑通说明基础环境没问题。另外如果你之前装过其他版本的OpenCV并且设置过OPENCV_DIR环境变量建议先临时删掉或者改个名。因为CMake在Configure时可能会去读这个变量导致找到错误的库。这个坑我踩过明明在编译4.5.1结果CMake找到了之前装的4.2.0的配置编译出来的东西各种奇怪报错。3. CMake-GUI配置的完整实操3.1 第一次Configure设定源码与生成目录打开CMake-GUI你会看到两个路径输入框。Where is the source code填D:/opencv_build/opencv-4.5.1。Where to build the binaries填D:/opencv_build/build。注意路径中的斜杠用正斜杠/或者反斜杠\都可以CMake会自动处理但不要用中文。填好之后点击左下角的Configure按钮。这时会弹出一个对话框让你选Generator。Generator选“Visual Studio 16 2019”Platform选“x64”。如果你选的是“Win32”编译出来的库是32位的和现在大多数项目不匹配。选好之后点Finish。接下来CMake会开始第一次扫描和配置。这个过程大概持续1-3分钟期间你会看到输出窗口里滚动各种检测信息。第一次Configure结束后中间列表里会出现大量红色条目这是正常的因为很多选项还没设置。不要慌也不要急着Generate红色条目需要你逐项检查。3.2 关键选项的勾选与路径填写红色条目里大部分保持默认即可但有几个必须手动改。我按重要性排序第一OPENCV_EXTRA_MODULES_PATH。找到这个条目在Value列填入D:/opencv_build/opencv_contrib-4.5.1/modules。注意路径要精确到modules文件夹不是contrib的根目录。填完之后CMake会把contrib里的所有模块纳入配置。第二BUILD_opencv_world。这个选项决定是否把所有模块合并成一个大的opencv_world451.dll。如果你希望最终只有一个库文件链接方便就勾上。但注意world模式下某些模块的符号可能冲突而且编译时间更长。我个人的习惯是不勾保持每个模块独立的lib和dll这样按需链接项目结构更清晰。第三BUILD_SHARED_LIBS。默认是勾上的表示编译动态库。如果你要静态库取消勾选。但取消之后还需要设置BUILD_WITH_STATIC_CRT为OFF除非你明确要用静态CRT以及确保所有第三方依赖也静态链接。第一次编译建议保持勾选。第四CMAKE_INSTALL_PREFIX。这个条目指定安装目录默认是C:/Program Files/opencv。改成D:/opencv_build/install避免往系统盘写文件需要管理员权限。第五OPENCV_ENABLE_NONFREE。如果你需要SIFT、SURF这些专利算法虽然专利已过期但OpenCV默认还是放在nonfree里就勾上。不需要的话保持默认。第六BUILD_opencv_python3。如果你不需要Python接口取消勾选能省不少编译时间。需要的话保持勾选并确认PYTHON3_EXECUTABLE指向正确的python.exe。第七WITH_CUDA。除非你有NVIDIA显卡并且装了CUDA Toolkit否则不要勾。勾了之后Configure会报找不到CUDA还得手动指定路径很麻烦。本文以CPU版本为主。改完这些之后再次点击Configure。这次红色条目会少很多但可能还会剩几个。比如PYTHON3_LIBRARY、PYTHON3_INCLUDE_DIR如果没自动找到需要手动指定。还有OPENCV_DOWNLOAD_PATH如果某些第三方依赖如ffmpeg需要在线下载确保网络通畅或者提前把下载好的文件放到这个目录。3.3 反复Configure直到红色消失CMake的配置过程可能需要反复点击Configure按钮。每次点击后它会重新检测依赖、更新缓存。直到所有红色条目消失输出窗口显示“Configuring done”才算配置完成。这里有一个经验如果某个红色条目反复出现怎么改都消不掉大概率是依赖缺失。比如FFMPEG相关的条目一直红说明ffmpeg的预编译包没下载成功。解决办法是手动去OpenCV的下载源把对应的文件下下来放到OPENCV_DOWNLOAD_PATH指定的目录里再重新Configure。还有一个常见问题CUDA相关的条目即使没勾WITH_CUDA也会出现红色。这是因为CMake检测到了系统里有CUDA的残留配置。解决办法是在搜索框里搜“CUDA”把所有CUDA开头的条目全部取消勾选或者清空值再Configure。配置完成后点击Generate按钮。如果一切顺利输出窗口会显示“Generating done”并且D:/opencv_build/build目录下会出现OpenCV.sln文件。这个就是VS2019的解决方案文件。4. VS2019编译与安装的详细步骤4.1 打开解决方案与编译配置选择双击OpenCV.slnVS2019会启动并加载解决方案。加载完成后注意看顶部工具栏的配置管理器。Solution Configuration选“Release”Solution Platform选“x64”。为什么先编Release因为Release版本优化充分编译速度快而且最终项目发布也是用Release。Debug版本可以后面再编用于调试。在解决方案资源管理器里你会看到上百个项目。不要一个一个去编直接右键点击顶层的Solution OpenCV选择生成解决方案。VS2019会按照依赖关系自动编译所有项目。这个过程非常耗时取决于你的CPU核心数。我实测在8核16线程的机器上完整编译大约需要25-40分钟。如果只编核心模块时间会短一些。编译过程中输出窗口会滚动大量信息。重点关注“错误”和“警告”。警告可以暂时忽略但错误必须解决。常见的错误包括找不到头文件通常是contrib路径没配对、链接错误通常是第三方库没编好、以及C标准不匹配OpenCV 4.5.1需要C11VS2019默认支持。4.2 编译过程中的典型报错与处理报错一fatal error C1083: 无法打开包括文件: opencv2/opencv_modules.hpp。这个文件是CMake生成的位于build/opencv2/目录下。如果报这个错说明CMake的Generate步骤没完全成功或者你手动清理了build目录里的某些文件。解决办法是回到CMake-GUI重新Configure和Generate。报错二LNK1181: 无法打开输入文件 xxx.lib。这通常是某个第三方依赖库没编译成功。比如libjpeg-turbo.lib、libpng.lib。你可以在解决方案里找到对应的项目比如jpeg、png单独右键编译它看具体报什么错。常见原因是NASM没装libjpeg-turbo需要汇编器。解决办法是下载NASM把nasm.exe放到PATH里或者在CMake里指定NASM_EXECUTABLE的路径。报错三error C2039: xxx: 不是 std 的成员。这是C标准库版本问题。OpenCV 4.5.1的某些代码用了C11的特性但VS2019默认可能用的是C14。解决办法是在CMake里设置CMAKE_CXX_STANDARD为11或者直接在VS的项目属性里把C语言标准改成ISO C11。报错四contrib模块编译失败提示某个头文件找不到。比如xfeatures2d模块报错。这通常是因为contrib的路径填错了或者contrib版本和主库不匹配。检查OPENCV_EXTRA_MODULES_PATH是否精确指向modules文件夹以及contrib的版本号是否为4.5.1。4.3 编译成功后的安装操作当输出窗口显示“生成: 成功 XX 个失败 0 个”时说明编译完成。接下来进行安装。在解决方案资源管理器里找到INSTALL项目通常在列表最下面右键点击选择仅生成INSTALL或者“生成”。这个操作会把编译好的头文件、lib、dll复制到CMAKE_INSTALL_PREFIX指定的目录也就是D:/opencv_build/install。安装完成后打开D:/opencv_build/install你会看到include、x64两个文件夹。include里是头文件x64/vc16/lib里是lib文件x64/vc16/bin里是dll文件。注意vc16对应VS2019MSVC 19.2xvc15对应VS2017。如果你看到的是vc15说明Generator选错了。提示安装完成后建议把D:/opencv_build/install/x64/vc16/bin添加到系统PATH环境变量里。这样运行exe时能自动找到OpenCV的dll。如果不想改PATH也可以把dll拷到exe同目录下。5. 在VS2019项目中链接OpenCV的实操5.1 新建测试项目与属性配置编译出来的库到底能不能用必须建一个测试项目验证。打开VS2019新建一个空项目C取名叫test_opencv。然后在项目属性里做三件事第一包含目录。在“VC目录” - “包含目录”里添加D:/opencv_build/install/include和D:/opencv_build/install/include/opencv2。注意只需要添加include根目录OpenCV的头文件里用的是相对路径。第二库目录。在“VC目录” - “库目录”里添加D:/opencv_build/install/x64/vc16/lib。第三附加依赖项。在“链接器” - “输入” - “附加依赖项”里添加你需要用到的lib文件。比如opencv_core451.lib、opencv_imgproc451.lib、opencv_highgui451.lib、opencv_imgcodecs451.lib。如果你编了contrib还需要加opencv_xfeatures2d451.lib等。注意Release配置加不带d的libDebug配置加带d的lib比如opencv_core451d.lib。5.2 一段最小验证代码配置好之后写一段最简单的代码测试#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放到项目目录下编译运行。如果能看到图片窗口并且控制台输出“OpenCV版本: 4.5.1”说明整个编译和链接流程完全成功。如果报错“找不到opencv_world451.dll”或者类似的dll缺失检查PATH是否包含bin目录或者把dll拷到exe旁边。5.3 Debug版本与Release版本的差异处理很多人在Release下编译成功切到Debug就报一堆链接错误。原因是Debug版本的lib文件名带d后缀而且依赖的运行时库也不同。你需要确保Debug配置的附加依赖项里所有lib都带d比如opencv_core451d.lib。如果你编译OpenCV时只编了Release那Debug项目是链接不上的。解决办法是回到VS2019把Solution Configuration切到Debug重新生成一遍。Debug编译同样耗时但为了调试必须编。Debug版本的dll也在bin目录下文件名带d比如opencv_core451d.dll。运行时需要确保能找到这些dll。我个人的习惯是Release和Debug都编然后在项目属性里用宏区分。比如在附加依赖项里写opencv_core451$(Configuration).lib但这样需要把Debug的lib命名成opencv_core451Debug.lib比较麻烦。更简单的办法是直接用VS的属性表Property Sheet分别建Release和Debug两个属性表各自配置对应的lib列表。6. 常见问题排查与避坑经验6.1 配置阶段的典型问题速查问题现象可能原因解决办法Configure时找不到C编译器VS2019未安装C工作负载打开VS Installer勾选“使用C的桌面开发”contrib模块未出现在列表中OPENCV_EXTRA_MODULES_PATH填错精确指向contrib的modules文件夹反复提示下载ffmpeg失败网络问题或下载源不可达手动下载ffmpeg包放到OPENCV_DOWNLOAD_PATHGenerate后没有OpenCV.slnConfigure未完全成功检查输出窗口是否有“Configuring done”编译时提示NASM未找到libjpeg-turbo需要汇编器安装NASM并加入PATH或指定NASM_EXECUTABLE6.2 编译阶段的避坑心得坑一路径中的空格。我见过有人在C:\Program Files\下面建build目录结果CMake生成的VS解决方案里路径带空格编译时各种找不到文件。绝对不要在带空格的路径下编译。坑二杀毒软件干扰。编译过程中会产生大量临时文件某些杀毒软件会实时扫描导致编译速度极慢甚至误报。建议编译期间临时关闭实时防护或者把build目录加入白名单。坑三内存不足。编译OpenCV的某些模块比如dnn非常吃内存16GB内存的机器在编译到后期时可能爆内存。解决办法是减少并行编译的项目数。在VS2019里工具 - 选项 - 项目和解决方案 - 生成并运行 - “最大并行项目生成数”改成2或3。坑四contrib模块的依赖冲突。某些contrib模块之间会互相依赖如果只勾选了一部分可能导致链接错误。建议第一次编译时全选contrib模块默认就是全选等编译成功后再按需裁剪。坑五install目录权限。如果CMAKE_INSTALL_PREFIX指向系统盘比如C:\Program FilesINSTALL步骤会因为权限不足失败。改成用户目录或者D盘即可。6.3 链接阶段的常见报错与解决报错LNK2019: 无法解析的外部符号。这通常是附加依赖项里漏了某个lib。比如用了cv::imshow但没加opencv_highgui451.lib。解决办法是查OpenCV文档确认该函数属于哪个模块把对应的lib加上。报错LNK2038: 检测到RuntimeLibrary的不匹配。这是Release和Debug混用导致的。Release项目链接了Debug的lib或者反过来。检查配置管理器确保Solution Configuration和项目配置一致。报错0xC000007B。这是32位和64位混用。你的项目是x64但链接了32位的dll或者PATH里找到了32位的dll。用Dependency Walker或者VS的“模块”窗口检查加载的dll位数。报错找不到opencv_world451.dll。如果你编了world模式但没把dll放到exe旁边或者PATH里没有bin目录。解决办法是把install/x64/vc16/bin加到PATH或者把dll拷到exe同目录。6.4 一个容易被忽略的细节OpenCV的版本宏编译完成后建议在代码里打印CV_VERSION宏确认版本号确实是4.5.1。我遇到过有人编译的是4.5.1但项目里链接了之前残留的4.2.0的lib导致运行时行为异常。检查方法是看opencv2/core/version.hpp里的CV_VERSION_MAJOR、CV_VERSION_MINOR、CV_VERSION_REVISION三个宏的值。另外如果你同时装了多个版本的OpenCV建议在项目属性里用绝对路径指定lib而不是依赖OPENCV_DIR环境变量。因为环境变量是全局的容易串。7. 编译后的库管理与多项目复用7.1 用属性表实现一次配置多处复用如果你有多个VS项目都需要链接OpenCV每个项目都手动配一遍包含目录、库目录、附加依赖项太累了。正确的做法是建一个属性表.props文件。在VS2019里打开“属性管理器”视图 - 其他窗口 - 属性管理器右键Release | x64选择“添加新项目属性表”命名成opencv451_release.props。然后在这个属性表里配置好所有路径和lib。之后新建项目时直接添加这个属性表即可一劳永逸。Debug版本同理建一个opencv451_debug.propslib列表里全部带d后缀。这样切换配置时VS会自动加载对应的属性表不会搞混。7.2 把OpenCV部署到其他机器如果你编译好的程序要拷到别的Win10机器上运行而那台机器没装OpenCV你需要把必要的dll一起带过去。最省事的办法是用windeployqt类似的工具但OpenCV没有官方部署工具。手动做法是把install/x64/vc16/bin下所有dll拷到exe同目录。如果嫌dll太多可以只拷你用到的模块对应的dll。比如只用了core、imgproc、imgcodecs、highgui就拷这四个的dll加上它们的依赖比如opencv_core451.dll依赖opencv_imgproc451.dll实际上core不依赖其他但imgcodecs依赖core和imgproc。更稳妥的办法是用Dependency Walker打开exe看它实际加载了哪些dll然后只拷这些。但注意OpenCV的dll之间也有依赖关系漏拷一个就会报错。7.3 后续升级与版本切换的注意事项如果将来要从4.5.1升级到4.6.0不要直接覆盖install目录。正确的做法是新建一个opencv_build_460目录重新走一遍编译流程install到D:/opencv_build/install_460。然后在项目属性表里改路径。这样两个版本可以共存方便回滚。另外OpenCV的contrib模块在不同版本间API可能有变化。升级后需要重新编译你的项目代码检查是否有函数签名变更。特别是xfeatures2d里的SIFT、SURF在4.5.1之后有调整。8. 一些个人体会与实用建议编译OpenCV这件事第一次做会觉得步骤繁琐、报错莫名其妙。但走通一遍之后你会发现它其实是一个很标准化的流程准备源码、CMake配置、VS编译、安装、链接。真正耗时间的不是操作而是等待编译和排查环境问题。我个人的建议是把整个编译过程录屏或者写成一个checklist。下次再编新版本时照着checklist走能避免90%的重复踩坑。另外编译成功后把build目录整个打包备份。如果以后CMake配置乱了直接删掉build重新解压备份比从头Configure快得多。还有一个技巧如果你只需要OpenCV的核心模块core、imgproc、imgcodecs、highgui可以在CMake里把其他模块全部取消勾选这样编译时间能从40分钟缩短到10分钟以内。对于大多数日常开发来说这四个模块已经够用了。contrib模块按需勾选不要一股脑全编。最后说一个关于VS2019和CMake配合的小细节CMake生成的VS解决方案里项目数量非常多加载和切换配置时VS可能会卡顿。如果你只是编译一次可以用命令行cmake --build . --config Release来编译比打开VS界面快。但如果你需要调试编译错误还是得用VS打开解决方案因为能看到具体的错误行和上下文。整个流程走下来最关键的其实就是耐心。CMake的红色条目一个个消掉编译错误一个个查链接问题一个个试。等你看到那个图片窗口弹出来控制台打印出“OpenCV版本: 4.5.1”的时候前面所有的折腾都值了。