企业官网建设流程全解析

1. 为什么我要把 pip 装的 OpenCV 和源码编译的 OpenCV 放在一起对比

很多人第一次在 Windows 或 Linux 上装 OpenCV，都是直接一句pip install opencv-python就完事了。跑个读图、缩放、边缘检测确实没问题，代码三行就能出结果。但只要项目稍微往深处走一点——比如要调用cv2.dnn跑自定义模型、要用 CUDA 加速、要接 GStreamer 做视频流、要处理某些特定编码格式的视频——你就会发现 pip 装的那个包突然"缺胳膊少腿"，报错信息还特别含糊，比如AttributeError: module 'cv2' has no attribute 'cuda'或者某个函数直接不存在。

这时候大多数人的第一反应是去搜"怎么装带 CUDA 的 OpenCV"，然后被一堆cmake -D WITH_CUDA=ON ...的长命令劝退。我当初也是这样，前前后后在不同机器上折腾了七八次，Windows 和 Linux 都踩过，才慢慢摸清楚这两条路线到底差在哪、文件层面到底装了什么、什么场景该选哪条路。

这篇笔记就是把我自己积累的对比经验整理出来。核心不是教你"复制粘贴一条命令"，而是让你搞清楚：pip 安装的 OpenCV 和 cmake 源码编译的 OpenCV，在文件结构、功能覆盖、依赖关系、可定制性上到底有什么区别，以及在不同操作系统上这些区别会怎么放大。看完之后，你应该能自己判断当前项目该用哪种方式，而不是盲目跟着教程走。

内容会涉及具体的目录结构、文件命名规律、编译产物对比、常见报错定位，以及我在实际项目里总结出来的取舍经验。无论你是刚接触 OpenCV 的新手，还是已经用过一段时间但没深究过安装机制的老手，应该都能从中找到对自己有用的部分。

2. pip 安装的 OpenCV 到底往磁盘里写了什么

2.1 包名背后的玄机：opencv-python 与 opencv-contrib-python 的区别

先把这个最基础但最容易搞混的点说清楚。pip 上的 OpenCV 相关包其实有好几个，名字看着差不多，装错了就是白忙活。

这里的关键点是：contrib 模块里有很多"看起来应该内置"的功能其实并不在主包里。比如 SIFT 在旧版本里属于 contrib，cv2.aruco、cv2.face、cv2.xfeatures2d这些也都在 contrib 里。我见过不少人装了opencv-python之后找不到某个函数，折腾半天才发现是包选错了。

另一个坑是headless版本。它去掉了所有 GUI 相关的依赖（比如 GTK、Qt），体积更小，但代价是cv2.imshow()、cv2.waitKey()这些函数直接不能用。如果你在服务器上跑推理，用 headless 完全没问题；但如果你本地开发时想弹个窗口看结果，那就得装非 headless 版本。

2.2 安装后的文件布局：一个自包含的二进制包

pip 安装 OpenCV 的本质，是下载一个已经编译好的 wheel 包，然后解压到你的 Python 环境的site-packages目录下。以 Linux 为例，装完之后大概长这样：

site-packages/ ├── cv2/ │ ├── __init__.py │ ├── cv2.abi3.so # 核心二进制模块（Linux） │ ├── cv2.cpython-xxx.so # 或者这种命名 │ ├── data/ │ │ └── haarcascades/ # 预训练的 Haar 分类器 │ ├── gapi/ # Graph API 相关 │ └── ... ├── opencv_python-4.x.x.dist-info/ │ ├── METADATA │ ├── RECORD │ └── ...

Windows 上则是cv2.pyd或者cv2.cp3x-win_amd64.pyd这样的文件。整个包是自包含的——它把 OpenCV 编译好的动态库、Python 绑定、必要的数据文件全部打包在一起，你不需要额外装任何系统级的 OpenCV 库。

这个设计的好处非常明显：安装简单、跨平台一致、不会和系统里其他库冲突。但坏处也同样明显：你拿到的是一个"黑盒"，编译时的选项是打包者定死的，你改不了。比如官方发布的 wheel 默认不开 CUDA、不开某些专利算法、不带某些视频编解码后端。你想要这些，pip 路线基本走不通。

2.3 版本选择与 Python 版本绑定关系

pip 装的 OpenCV 和你的 Python 版本是强绑定的。每个 wheel 都是针对特定 Python 版本（3.8、3.9、3.10……）和特定平台（win_amd64、manylinux、macosx）编译的。这意味着：

• 你升级了 Python 小版本，可能就得重新装对应版本的 OpenCV
• 某些冷门平台（比如 ARM 上的某些发行版）可能没有现成 wheel，pip 会尝试从源码编译，然后大概率失败
• 不同 Python 版本能装到的 OpenCV 版本上限不同，老 Python 可能装不了最新 OpenCV

我自己的经验是，用 pip 装 OpenCV 时，先pip debug --verbose看一下当前环境支持的 wheel 标签，再去 PyPI 页面确认有没有对应版本。如果发现只能装很老的版本，那说明你的 Python 或平台太特殊了，这时候反而应该考虑源码编译。

3. cmake 源码编译 OpenCV 的产物结构长什么样

3.1 编译流程的四个阶段与关键产物

源码编译 OpenCV 不是一条命令的事，它至少经过四个阶段，每个阶段都会产生不同的文件。理解这些阶段，你才能知道最后装到系统里的到底是什么。

第一阶段：配置（cmake configure）。你在一个 build 目录里运行cmake ..，cmake 会检测你的系统环境、找到编译器、检查依赖库、生成 Makefile 或 Visual Studio 工程文件。这个阶段最重要的产物是CMakeCache.txt，里面记录了你所有的编译选项。如果后面编译出问题，第一件事就是回来看这个文件里某个选项是不是没打开。

第二阶段：编译（build）。运行make -j$(nproc)或cmake --build .，编译器开始把成千上万个源文件编译成目标文件，最后链接成动态库。这个阶段产物在lib/目录下，你会看到libopencv_core.so、libopencv_imgproc.so、libopencv_dnn.so等等，每个模块一个库。

第三阶段：安装（install）。运行make install，把编译好的库、头文件、配置文件复制到你指定的安装前缀（默认/usr/local）。这一步决定了最终文件在系统里的布局。

第四阶段：Python 绑定。如果你开了BUILD_opencv_python3，还会生成cv2.cpython-xxx.so这样的 Python 模块，通常放在lib/python3.x/site-packages/cv2/下。

3.2 Linux 下的典型安装布局

在 Linux 上，如果你用默认前缀/usr/local，装完之后大概是这样：

/usr/local/ ├── bin/ │ └── opencv_version # 版本查询工具 ├── include/ │ └── opencv4/ │ └── opencv2/ # 所有头文件 │ ├── core.hpp │ ├── imgproc.hpp │ └── ... ├── lib/ │ ├── libopencv_core.so │ ├── libopencv_core.so.4.x │ ├── libopencv_imgproc.so │ ├── ... │ ├── cmake/ │ │ └── opencv4/ # 供其他 cmake 项目 find_package 用 │ └── pkgconfig/ │ └── opencv4.pc # 供 pkg-config 用 └── lib/python3.x/site-packages/cv2/ └── cv2.cpython-xxx.so

这个布局是系统级的。任何 C++ 项目只要在CMakeLists.txt里写find_package(OpenCV REQUIRED)，cmake 就能在/usr/local/lib/cmake/opencv4/找到配置文件，自动帮你把 include 路径和链接库配好。Python 那边则通过PYTHONPATH或者把.so复制到 site-packages 来使用。

3.3 Windows 下的目录结构与 DLL 分布

Windows 上源码编译的布局和 Linux 差别很大，尤其是动态库的分布。用 Visual Studio 编译时，产物通常在build/install/下：

install/ ├── bin/ │ ├── opencv_core4xx.dll │ ├── opencv_imgproc4xx.dll │ ├── opencv_world4xx.dll # 如果开了 BUILD_opencv_world │ └── ... ├── include/ │ └── opencv2/ ├── lib/ │ ├── opencv_core4xx.lib # 导入库，链接时用 │ ├── opencv_imgproc4xx.lib │ └── ... ├── etc/ │ └── haarcascades/ └── python/ └── cv2/ └── cv2.pyd

Windows 上最容易踩的坑是DLL 找不到。编译时链接的是.lib导入库，运行时需要对应的.dll在PATH里。很多人编译完 Python 绑定后import cv2报ImportError: DLL load failed，就是因为opencv_core4xx.dll这些没加到系统 PATH，或者没复制到cv2目录旁边。解决办法要么是把install/bin加进 PATH，要么用工具把 DLL 复制到cv2.pyd同目录。

3.4 BUILD_opencv_world 选项对文件数量的影响

源码编译时有个很实用的选项叫BUILD_opencv_world。默认情况下，OpenCV 每个模块编译成一个独立的库，你会得到几十个.so或.dll。开了 world 之后，所有模块合并成一个大库libopencv_world.so或opencv_world4xx.dll。

这个选项的取舍很实际：

• 开 world：文件少、部署简单、链接时只写一个库名。缺点是体积大，哪怕你只用 core 和 imgproc，也会把 dnn、video 等全部加载进来。
• 不开 world：文件多、部署时要挑需要的库。但体积可控，适合嵌入式或对启动速度敏感的场景。

我在做桌面应用时一般开 world，省得部署时漏拷 DLL；做服务端推理时不开，只链接需要的模块，镜像能小不少。

4. 两条路线在功能覆盖上的真实差距

4.1 CUDA 与硬件加速：pip 版本为什么用不了

这是两条路线差距最大的地方。pip 官方发布的 wheel 是不带 CUDA 支持的。也就是说，你pip install opencv-python之后，cv2.cuda.getCudaEnabledDeviceCount()会返回 0，所有cv2.cuda.*的函数要么不存在，要么直接报错。

原因很简单：CUDA 版本的 OpenCV 需要链接 CUDA 运行时、cuDNN、NVIDIA 的驱动库，而且编译出来的 wheel 会非常大（几百 MB 到 1 GB 以上），还要绑定特定的 CUDA 版本。官方不可能为所有 CUDA 版本都发布 wheel，所以干脆不发。

想要 CUDA 加速，只有两条路：源码编译，或者找第三方预编译的包。第三方包质量参差不齐，而且版本更新滞后，我一般还是自己编译。编译时关键选项是：

cmake -D WITH_CUDA=ON \ -D CUDA_ARCH_BIN="7.5;8.6" \ -D WITH_CUDNN=ON \ -D OPENCV_DNN_CUDA=ON \ -D CUDA_FAST_MATH=ON \ ..

CUDA_ARCH_BIN要填你显卡的计算能力，填错了要么跑不了要么性能差。这个值可以去显卡规格表查，比如某代显卡是 8.6，某代是 7.5。填多个用分号隔开，但每多一个都会增加编译时间。

4.2 视频编解码后端：GStreamer、FFmpeg 的取舍

pip 版本的 OpenCV 内置了 FFmpeg 支持，能读常见的 mp4、avi。但它不带 GStreamer，也不带某些专利编解码器（比如 H.265 的某些实现）。如果你的项目要接 RTSP 流、要用硬件编解码、要处理特殊格式，pip 版本经常会力不从心。

源码编译时，你可以通过WITH_GSTREAMER=ON、WITH_FFMPEG=ON来精确控制后端。Linux 上还要先装 GStreamer 的开发包：

sudo apt install libgstreamer1.0-dev \ libgstreamer-plugins-base1.0-dev \ libgstreamer-plugins-bad1.0-dev

装完之后编译，cv2.getBuildInformation()里就能看到 GStreamer 是 YES。这个信息在排查视频问题时特别有用，我每次装完 OpenCV 第一件事就是打印这个，确认所有需要的后端都开了。

4.3 contrib 模块与专利算法的编译开关

contrib 模块在源码编译时是通过OPENCV_EXTRA_MODULES_PATH引入的。你需要先把 opencv_contrib 仓库 clone 下来，然后在 cmake 时指定路径：

cmake -D OPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ..

这里有个细节：contrib 里有些算法涉及专利（比如 SIFT 曾经是），编译时会有OPENCV_ENABLE_NONFREE选项。开了之后才能用某些非免费算法。pip 的 contrib 包一般是开了的，但源码编译默认不开，需要手动加-D OPENCV_ENABLE_NONFREE=ON。

我遇到过有人编译完 contrib 后发现cv2.xfeatures2d.SIFT_create()报错，就是因为没开这个选项。不过新版本 OpenCV 里 SIFT 已经进主模块了，这个坑现在踩的人少了。

4.4 自定义模块与裁剪：源码编译的独门优势

源码编译最大的价值其实是可裁剪。你可以关掉所有不需要的模块，只编译自己用的那几个。比如做一个纯图像处理的服务，不需要 video、不需要 dnn、不需要 highgui，那就可以：

cmake -D BUILD_opencv_video=OFF \ -D BUILD_opencv_dnn=OFF \ -D BUILD_opencv_highgui=OFF \ -D BUILD_opencv_videoio=OFF \ ..

编译出来的库体积能小一大半，启动也更快。这种精细控制在 pip 路线里是完全做不到的。另外，如果你有自己的算法想集成进 OpenCV 的模块体系，也只能走源码编译，把自定义模块放进modules/目录一起编译。

5. Windows 与 Linux 编译安装的实操差异

5.1 Linux 下的依赖准备与 cmake 命令模板

Linux 编译 OpenCV 相对省心，因为依赖管理有包管理器。以 Ubuntu 为例，编译前先装这一堆：

sudo apt update sudo apt install build-essential cmake git pkg-config \ libgtk-3-dev libavcodec-dev libavformat-dev \ libswscale-dev libv4l-dev libxvidcore-dev \ libx264-dev libjpeg-dev libpng-dev libtiff-dev \ libatlas-base-dev gfortran python3-dev

这些依赖里，libgtk-3-dev是给 highgui 用的，没有它imshow就不能用；libavcodec-dev那一串是 FFmpeg 相关；libatlas-base-dev是线性代数加速。少装哪个，cmake 配置阶段就会把对应功能标成 NO，编译完才发现功能缺失。

配置命令我常用的模板：

mkdir build && cd build cmake -D CMAKE_BUILD_TYPE=RELEASE \ -D CMAKE_INSTALL_PREFIX=/usr/local \ -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \ -D WITH_CUDA=OFF \ -D WITH_GSTREAMER=ON \ -D BUILD_opencv_python3=ON \ -D PYTHON3_EXECUTABLE=$(which python3) \ -D BUILD_EXAMPLES=OFF \ .. make -j$(nproc) sudo make install sudo ldconfig

ldconfig这步很多人会忘，导致装完之后程序找不到libopencv_core.so。它的作用是刷新系统的动态库缓存，让新装的库能被立即找到。

5.2 Windows 下 Visual Studio 与 MinGW 的选择

Windows 上编译 OpenCV，编译器选择是个大问题。主流是 Visual Studio（MSVC）和 MinGW 两派。

MSVC是官方支持最好的路线。你需要装 Visual Studio（社区版就够），安装时勾选"使用 C++ 的桌面开发"。然后用 cmake-gui 或者命令行配置，生成.sln工程文件，用 VS 打开编译。优点是兼容性好、Python 绑定容易成功；缺点是编译慢、生成的库依赖 MSVC 运行时。

MinGW适合习惯 GCC 的人，但坑更多。Python 绑定经常编译失败，因为 MinGW 编译出的.pyd和官方 Python（用 MSVC 编译的）ABI 不兼容。我试过几次 MinGW 路线，最后都放弃了，Windows 上还是老老实实用 MSVC。

配置命令大概是这样：

cmake -G "Visual Studio 17 2022" -A x64 ^ -D CMAKE_INSTALL_PREFIX=C:/opencv/build/install ^ -D OPENCV_EXTRA_MODULES_PATH=C:/opencv/opencv_contrib/modules ^ -D BUILD_opencv_world=ON ^ -D BUILD_EXAMPLES=OFF ^ .. cmake --build . --config Release --target INSTALL

注意-A x64指定 64 位，不写的话默认可能是 32 位，装出来的库和 64 位 Python 对不上。

5.3 编译时间、内存占用与并行度调优

源码编译 OpenCV 是个体力活。全量编译（带 contrib、带 CUDA）在普通机器上可能要一两个小时，内存占用也高。make -j$(nproc)里的并行度不是越高越好，因为每个编译单元都吃内存，并行度太高会 OOM。

我的经验值：

如果编译中途 OOM 被杀，降低并行度重来即可，已经编译好的目标文件不会丢，make 会跳过它们。这也是为什么我建议第一次编译时不要一上来就-j16，稳一点用-j4，出问题好定位。

5.4 安装后的环境变量与路径配置

Linux 上装到/usr/local后，通常不用额外配环境变量，因为/usr/local/lib本来就在默认搜索路径里。但如果装到自定义前缀（比如/opt/opencv），就需要：

export LD_LIBRARY_PATH=/opt/opencv/lib:$LD_LIBRARY_PATH export PKG_CONFIG_PATH=/opt/opencv/lib/pkgconfig:$PKG_CONFIG_PATH

Python 那边还要把cv2模块路径加进PYTHONPATH，或者做个软链接到 site-packages。

Windows 上主要是 PATH。把install/bin加进系统 PATH，Python 才能找到 DLL。另外如果同时装了 pip 版和源码版，import cv2到底加载哪个取决于sys.path的顺序，很容易搞混。我的做法是：同一个环境里只保留一种安装方式，要么 pip 要么源码，不要混着来。

6. 踩坑实录：那些让我熬夜的报错与排查过程

6.1 import cv2 报 DLL load failed 的完整排查链路

这个报错在 Windows 源码编译后极其常见。我第一次遇到时，import cv2直接抛ImportError: DLL load failed while importing cv2: 找不到指定的模块，没有任何更多信息。

排查过程是这样的：

第一步，确认cv2.pyd文件存在。去install/python/cv2/下看，文件在，说明编译成功了。

第二步，用 Dependency Walker 或者dumpbin /dependents cv2.pyd看它依赖哪些 DLL。发现它依赖opencv_world4xx.dll、python3x.dll等。

第三步，检查这些 DLL 在不在 PATH 里。opencv_world4xx.dll在install/bin/下，但这个目录没加进 PATH。把它加进去，重新import cv2，还是报错。

第四步，继续用dumpbin看opencv_world4xx.dll的依赖，发现它依赖 MSVC 运行时库vcruntime140.dll、msvcp140.dll。这些在装了 VS 的机器上有，但目标机器可能没有。

第五步，最终解决方案：把install/bin加进 PATH，同时确保 MSVC 运行时库存在（装 VC++ Redistributable）。或者更省事的办法，把opencv_world4xx.dll直接复制到cv2.pyd同目录，这样 Python 加载cv2.pyd时会在同目录找依赖。

这个排查链路的关键是逐层看依赖，不要停在第一层。很多人看到 DLL load failed 就以为是 OpenCV 没编译好，其实往往是依赖的依赖缺失。

6.2 版本冲突：pip 与源码版共存时的加载顺序问题

有次我在一个环境里先pip install opencv-python，后来又源码编译装了一遍。结果import cv2之后cv2.__version__显示的是 pip 版，但我明明想用源码版。

原因在于sys.path的搜索顺序。pip 版装在site-packages/cv2/，源码版可能装在/usr/local/lib/python3.x/site-packages/cv2/，如果前者在sys.path里靠前，就会优先加载。

排查方法：

import cv2 print(cv2.__file__) print(cv2.__version__)

__file__会告诉你实际加载的是哪个文件。如果发现加载错了，要么卸载 pip 版，要么调整PYTHONPATH顺序。我的建议还是那句话：一个环境只留一种，别给自己找麻烦。

6.3 cmake 配置阶段找不到 Python 的定位方法

源码编译 Python 绑定时，cmake 配置阶段经常报找不到 Python 库。典型报错是Could NOT find Python3 (missing: Python3_LIBRARIES Python3_INCLUDE_DIRS)。

这时候要手动指定：

cmake -D PYTHON3_EXECUTABLE=/usr/bin/python3 \ -D PYTHON3_INCLUDE_DIR=/usr/include/python3.10 \ -D PYTHON3_LIBRARY=/usr/lib/x86_64-linux-gnu/libpython3.10.so \ -D PYTHON3_PACKAGES_PATH=/usr/lib/python3/dist-packages \ ..

路径要根据你的系统实际位置填。用python3 -c "import sysconfig; print(sysconfig.get_paths())"可以查到准确路径。Windows 上则是找python3x.lib和Python.h的位置。

配置成功后，cmake 输出里会有Python 3: YES之类的字样，编译完才会有cv2.pyd或cv2.so。如果配置阶段就是 NO，后面编译再久也不会有 Python 模块。

6.4 编译到一半内存不足被杀的处理经验

前面提过并行度的问题，这里展开说。编译 OpenCV 的 dnn 模块时，某些源文件特别大，单个编译单元可能吃 2-3 GB 内存。如果你-j8同时编译 8 个这样的文件，16 GB 内存瞬间就满了，然后 OOM killer 会杀掉编译进程。

表现是：终端突然显示Killed，或者make: *** [xxx] Error 137。137 就是 128+9，9 是 SIGKILL，典型的 OOM。

处理办法：

• 降低并行度，-j2或-j1重来
• 加 swap 分区，给系统更多虚拟内存
• 单独编译大模块，make opencv_dnn -j1，然后再整体make

我现在的习惯是，第一次编译用保守的-j4，确认能过之后再考虑提速。毕竟编译失败重来的时间成本，比省下的那点并行时间高多了。

7. 到底该选哪条路：基于场景的决策清单

7.1 快速原型与教学演示：pip 完胜

如果你的需求是跑个 demo、做个课程作业、验证一个算法思路，pip 是绝对首选。一条命令搞定，不用管依赖、不用等编译、跨平台一致。opencv-python加opencv-contrib-python基本覆盖了 90% 的常见需求。

我给学生或者刚入门的朋友的建议都是：先用 pip 把东西跑起来，把算法逻辑搞清楚。等你真的遇到 pip 解决不了的问题，再去折腾源码编译。不要一上来就编译，那会消耗掉你所有的热情。

7.2 生产部署与性能敏感场景：源码编译的必要性

一旦进入生产环境，情况就变了。你需要考虑：

• 推理要不要 GPU 加速（CUDA）
• 视频流要不要特定后端（GStreamer）
• 镜像体积要不要裁剪（关掉不用的模块）
• 部署环境有没有 pip 版覆盖不到的功能

这些需求里只要中一条，源码编译就基本是必选项。我做过一个视频分析的服务，需要接 RTSP 流并做硬件解码，pip 版死活搞不定，最后源码编译开 GStreamer 才解决。虽然编译花了一小时，但后面稳定跑了半年，值。

7.3 混合策略：用 pip 开发、用源码部署

其实这两条路不是非此即彼。我现在的常用做法是混合：

• 本地开发机用 pip 版，快速迭代算法
• 部署环境用源码编译版，开需要的功能
• 两边用同一份 Python 代码，通过cv2.getBuildInformation()检查功能可用性

这样开发效率高，部署又能满足性能要求。唯一要注意的是，本地测试时如果用到某个 pip 版没有的功能，要提前在源码版环境里验证，别等到部署了才发现。

7.4 一张表看清两条路线的取舍

这张表我建议存下来，下次纠结用哪种方式时对照一下，基本能快速做决定。

8. 几个容易被忽略的细节与我的个人习惯

8.1 编译前先跑一遍 getBuildInformation 做基线

不管你用哪种方式装完 OpenCV，第一件事都应该是：

import cv2 print(cv2.getBuildInformation())

这个输出会列出所有编译选项：CUDA 是 YES 还是 NO、GStreamer 有没有、FFmpeg 版本、contrib 模块列表等等。把它保存下来作为基线，以后出问题一对比就知道哪里变了。我习惯把它存成一个文本文件放在项目根目录，换机器时直接 diff。

8.2 保留 CMakeCache.txt 作为编译配置的"存档"

源码编译时，build/CMakeCache.txt记录了你所有的配置选项。这个文件千万别删。下次想重新编译（比如升级 OpenCV 版本），直接复用这个 cache，cmake 会沿用之前的选项，省得你重新回忆当时开了哪些开关。

我的做法是，编译成功后把CMakeCache.txt复制一份到项目文档里，标注好日期和用途。换机器或者重装系统时，照着这个文件重新配置，能少踩很多坑。

8.3 用虚拟环境隔离不同版本的 OpenCV

Python 这边，强烈建议用 venv 或 conda 隔离环境。不同项目可能需要不同版本的 OpenCV，全局装一个迟早冲突。源码编译的 Python 绑定也可以装进虚拟环境，只要编译时PYTHON3_PACKAGES_PATH指向虚拟环境的 site-packages 就行。

我自己的习惯是，每个需要 OpenCV 的项目一个独立 venv，里面要么 pip 装要么源码编译装，绝不混用。这样import cv2加载哪个版本永远是确定的，排查问题也简单。

8.4 记录每次编译的完整命令，方便复现

最后一个小习惯：把每次编译 OpenCV 的完整命令（包括 cmake 配置和 make 命令）记在一个build_notes.md里。包括当时的系统版本、依赖版本、遇到的问题和解决办法。这个记录在半年后你重新编译时，价值巨大——因为那时候你早就忘了当时为什么加某个选项了。

我自己就吃过亏，有次重装系统后重新编译，忘了当时开了OPENCV_ENABLE_NONFREE，结果某个算法用不了，排查了半天才想起来。从那以后，每次编译必记录，再也没犯过同样的错。