OpenCV 2.4.13 安装指北：源码编译、环境配置与五条血泪排错记录

简介：面向计算机视觉与图像处理开发者，该zip压缩包提供的是OpenCV 2.4.13.3经典旧版安装资源，适合需要维护旧项目、复现历史算法或学习传统视觉知识的用户；相比高版本OpenCV，2.4.x在函数命名与调用方式上存在差异，保留这一版本可有效规避接口迁移带来的代码修改，也方便直接参照许多旧版教材与课程中的写法。压缩包整体大小约90.16MB，体积适中，下载后即可解压保存或迁移使用；详情页未给出文件总数与类型明细，故不再罗列。目前已有223人学习下载，说明该版本在环境和工程维护中仍有实际需求。作者在资源描述中提供了配套安装流程链接，能够帮助用户快速完成环境配置，规避动态库缺失、环境变量未设置等常见问题，省去自行编译源码的繁琐步骤，尤其适合在Windows下配合传统C/C++工程使用，可直接进入算法调试环节。无论是边缘检测、模板匹配还是特征点提取等基础实验，该版本都能提供成熟的接口和参考实现，便于快速学习；若项目中的第三方依赖锁定在OpenCV 2.4系列，这份压缩包也能作为稳定依赖长期留存，降低复现实验结果时的环境波动风险。

1. 为什么还在装 OpenCV 2.4.13：老项目版本回退的真实场景

OpenCV 都出到 4.x、5.x 了，还有人满世界找 opencv.2.4.13.zip 这个老版本，我一开始也不理解。直到接手一个维护了五六年的图像处理项目，代码里全是 cv::SIFT、cv::HOGDescriptor 那套 2.4 时代的写法，用新版本编译直接报一堆 API 找不到，才明白老版本不是没人用，是存量代码把它焊死了。

这个版本卡在一个微妙的节点上：它是 OpenCV 2.4 系列的最终版本，之后项目就转向 3.x 的大改动。很多算法模块的 API 在 3.0 里被重构过，老代码想迁过去等于重写一遍。所以这篇笔记就是写给那些必须在这个版本上做开发的人：项目维护、算法复现、嵌入式交叉编译，总有一个理由让你绕不开它。

我的建议是不管你是 Windows、Linux 还是 macOS，先把环境准备、编译参数和验证方法看完一遍再动手。装这个版本翻车率不低，但坑是固定的，照着踩过的路线走，半小时能跑通。

2. 环境准备与版本选择：依赖项对照与下载取舍

2.1 三个平台的依赖清单

先说结论：OpenCV 2.4.13 对操作系统不挑，挑的是编译器。我用三个环境分别装过一遍，依赖差异主要在底层库上。Windows 上最省事，官方直接给了预编译的 exe 安装包，解压就能用；Linux 和 macOS 建议从源码编译，因为预编译包连的是 glibc 和系统库，换台机器就可能起不来。

一个容易忽略的点：2.4.13 的时代还没有 CMake 4.x，用新版 CMake 编译老源码经常会因为策略变更报一堆 deprecation warning，虽然大多数不影响生成，但有一个坑我后面会专门讲。建议 Windows 上装 CMake 3.10 到 3.20 之间，Linux 上尽量用 apt 或 yum 源里的版本，不要太激进。

2.2 Python 版本怎么选

很多人装这个版本目的是用 cv2 的 Python 接口，这块特别容易踩空。OpenCV 2.4.13 官方预编译包里带的是 Python 2.7 的绑定，如果你机器上装的是 Python 3.6 以上，import cv2 会直接告诉你找不到模块。想在 Python 3 里用，必须自己从源码编译，而且要注意指定 PYTHON3_EXECUTABLE 这个变量。

我一般会这样判断该选哪套方案：只写 C++ 就用官方预编译包，简单直接；必须用 Python 3 就老实走源码编译流程。如果你看到网上有人说把 cv2.pyd 文件拷贝到 site-packages 目录就行，那是在 2.4.13 之前的版本成立的，这个版本直接拷通常会因为缺少 MSVCP140.dll 报错，本质上是运行时库没配上。

2.3 从哪下载：构建目录结构先记好

无论走哪条路，先把目录结构搞清楚。官方 zip 解压后是这样的框架：

OpenCV/ ├── build/ │ ├── include/ # C/C++ 头文件 │ ├── x64/ │ │ ├── vc12/lib/ # VS2013 版静态库 │ │ ├── vc14/lib/ # VS2015 版静态库 │ │ └── vc15/lib/ # VS2017 版静态库 │ └── bin/ # 运行时 DLL ├── sources/ │ ├── modules/ # 各个模块源码 │ └── CMakeLists.txt └── LICENSE.txt

注意 x64 下分了三套 lib 目录，分别对应 VS 2013、2015、2017 的运行时库版本。C++ 项目编译时要严格匹配工具集版本，用 VS2017 编译却链 vc14 的 lib，链接阶段会出现各种 LNK 冲突，玄学得很。我之前就翻车过，最后老老实实把项目迁移到对应工具集才跑通。下载完成后先别急着往下走，把 build 目录里 vc12、vc14、vc15 都保留好，后面配置项目时多一个选择。

3. 源码编译 OpenCV 2.4.13：CMake 参数取舍与完整流程

3.1 为什么不用预编译包直接开干

如果你要用 Python 3 绑定、要自定义裁剪模块、要做交叉编译，预编译包就不够用了。源码编译从好处的角度说，一是在 CMake 里可以关掉不需要的模块缩短编译时间，二是在 CUDA 等扩展支持上有更高灵活度。代价是第一次编译容易翻车，因为 2.4.13 源码相对老，和新版工具链之间有些已知的兼容性裂缝。

以 Ubuntu 20.04 为例，先把编译工具链和底层依赖装齐。下面这个命令是跑源码编译的基础套餐：

sudo apt-get update sudo apt-get install -y build-essential cmake pkg-config \ libgtk2.0-dev libavcodec-dev libavformat-dev libswscale-dev \ libjpeg-dev libpng-dev libtiff-dev libdc1394-22-dev

代码逻辑说明：build-essential 提供 GCC 编译器，libgtk2.0-dev 是 GUI 模块 highgui 在 Linux 下依赖的图形库，没有它 CMake 配置阶段会跳过 WITH_GTK，人脸检测里的 imshow 窗口功能直接残废。libavcodec 系列是视频读写模块 videoio 的依赖，补上之后才能支持 avi 之外更多容器格式。

3.2 CMake 配置：哪些参数必须动

进入源码根目录，我通常单独建一个 build 目录，把中间产物和源码分开：

cd opencv-2.4.13/sources mkdir build && cd build cmake -D CMAKE_BUILD_TYPE=RELEASE \ -D CMAKE_INSTALL_PREFIX=/usr/local/opencv2.4.13 \ -D WITH_TBB=OFF \ -D WITH_CUDA=OFF \ -D BUILD_opencv_python3=ON \ -D BUILD_opencv_python=OFF \ -D PYTHON3_EXECUTABLE=$(which python3) \ -D BUILD_EXAMPLES=OFF ..

参数含义逐个说：CMAKE_INSTALL_PREFIX 是指定安装路径，我习惯把 OpenCV 2.4.13 独立装到一个目录下，不污染系统全局的 /usr/local，这样以后如果要装 3.x 或 4.x 版本，两边共存不会互相覆盖头文件。WITH_TBB 默认是 ON 但 2.4.13 对 TBB 的兼容性不太好，版本稍微新一点就在编译时触发一堆模板编译错误，直接把它的开关关掉是最省心的。WITH_CUDA 同理，除非你确定自己有匹配版本的 CUDA 工具包，否则别开，否则 CMake 探测阶段就会报错。

Python 部分的两个参数要特别注意：BUILD_opencv_python 管的是 Python 2.7 绑定，BUILD_opencv_python3 是 Python 3 绑定，我目标机器上是 Python 3.8 就把 2 关掉 3 打开。PYTHON3_EXECUTABLE 执行 which python3 拿到解释器绝对路径，传给 CMake 告诉它目标 Python 在哪。编译生成的 cv2 模块最终会以cv2.cpython-38-x86_64-linux-gnu.so的形式输出到 build 目录的 lib 下，后续手动拷贝到 site-packages。

3.3 编译和安装：字数和等待时间成正比

配置完成后开始编译，这一步要有耐心：

make -j$(nproc) sudo make install

-j 指定并行编译的核数，nproc 可以自动返回 CPU 核心数。这一步时间因机器而异，8 核大概 10 分钟，核心少的可能要等半小时以上。如果在 make 过程中中断，重新执行时 make 会从断点继续，不用重新 cmake。

编译结束后，安装动作是把头文件、静态库、动态库和 CMake 配置文件一起拷贝到 CMAKE_INSTALL_PREFIX 指定路径下。有几个文件需要确认一下，因为后面的项目配置和 Python 导入都用得着：

ls /usr/local/opencv2.4.13/lib ls /usr/local/opencv2.4.13/bin find / -name "cv2*.so" 2>/dev/null

正常输出应该包含 libopencv_core.so、libopencv_imgproc.so、libopencv_highgui.so 等若干库文件，以及 OpenCVConfig.cmake 这个找包配置文件。cv2 的 Python 扩展文件在 opencv-2.4.13/sources/build/lib 目录里，不在安装目录下，这算 2.4.13 的一个特点，Python 模块是编译产物并没有跟随 install 步骤安装到系统 site-packages。我当时直接被这步坑到，以为安装失败了，后来才发现文件安静的躺在 build 目录。

3.4 把 Python 模块装进系统

找到编译生成的cv2.cpython-38-x86_64-linux-gnu.so文件后，把它复制到 Python 的 site-packages 目录：

cp build/lib/cv2*.so ~/.local/lib/python3.8/site-packages/ python3 -c "import cv2; print(cv2.__version__)"

复制到用户目录的 site-packages 是不需要 root 权限的常见做法，不影响系统级环境。如果导入时报undefined symbol: _XOpenDisplay之类错误，说明编译时 GTK 相关的头文件缺失但不影响生成，只是模块加载时符号解析失败。严格来说这属于依赖不完整导致的运行期问题，解决思路是回到 cmake 那一步，确认 WITH_GTK 的检测结果是 1，不要含混过关。

4. 环境配置与项目对接：路径、DLL 与 CMakeLists.txt

4.1 头文件和库路径：三个容易写错的位置

源码编译安装完成后，下一个任务就是让项目代码能找到这套 OpenCV 2.4.13。如果是 C++ 项目，无外乎手动设置路径或者通过 CMake find_package 机制。我在这步见过最多的翻车就是路径写错：把 include 路径写到源码目录而非安装目录，或者把 lib 路径指向 build 目录而安装目录下是空的。

正确写法是 include 指向/usr/local/opencv2.4.13/include，这里只放 opencv2 一个子目录。lib 路径指向/usr/local/opencv2.4.13/lib，里面是编译出来的所有共享库。用 CMake 的写法是：

cmake_minimum_required(VERSION 3.10) project(old_project) set(OpenCV_DIR "/usr/local/opencv2.4.13/share/OpenCV") find_package(OpenCV 2.4.13 REQUIRED) include_directories(${OpenCV_INCLUDE_DIRS}) add_executable(demo demo.cpp) target_link_libraries(demo ${OpenCV_LIBS})

OpenCV_DIR 这个变量是网上教程最容易一笔带过的地方。它的值必须指向安装目录下存放 OpenCVConfig.cmake 的那个路径，不是 include 路径，也不是 lib 路径。如果你跟我一样用了自定义 CMAKE_INSTALL_PREFIX，这个路径在默认配置基础上会多一层 share/OpenCV，写错的话 find_package 会直接报找不到包。

4.2 Windows 下 DLL 运行库的配置差别

Windows 环境要处理的问题完全不同。如果是用官方预编译包，解压后 x64/vc15/bin 目录下有一堆 DLL 文件。编译链接时项目属性里要配 Include 路径、Library 路径和附加依赖项，但程序运行时系统会在 PATH 里搜索 DLL。最简单的方案是把 bin 目录加进系统 PATH，或者把整个 bin 目录内容拷贝到 exe 所在目录。

需要特别注意一点：2.4.13 目录下的 opencv_world 系列 DLL 不是默认编译生成的，预编译包里没有。如果项目只链了一个 opencv_world2413.lib，运行时会提示找不到 opencv_world2413.dll，要去源码工程里开启 BUILD_opencv_world 再编译才能拿到合并版库。如果你依赖的是传统模块化 lib，像 opencv_core2413.lib、opencv_highgui2413.lib 这些，那就需要把这些对应的 DLL 都留在运行目录里。

我在 Windows 上装完经常用一个脚本一次性把 DLL 拷到目标目录：

copy "D:\opencv\build\x64\vc15\bin\*.dll" "C:\projects\demo\x64\Debug\"

这样做的好处是部署时不用用户再去配 PATH，缺点是二进制体积会变大，Debug 模式下光 OpenCV 的 DLL 就几十 MB。生产环境我会反过来做，稳定后只挑实际用到的模块 DLL 拷过去，减少体积和依赖暴露面。

4.3 兼容性检查：永远要把工具集版本对齐

Visual Studio 版本和 opencv_world 的对应关系到 2.4.13 这里特别严格。VS2013 对应 vc12，VS2015 对应 vc14，VS2017 对应 vc15。版本不对情况下链接可以过，但运行时会载入失败，或者出现内存访问冲突，原因就是 C++ 标准库在不同工具集间的 ABI 差异。

我之前有个项目用的 VS2017，但预编译包里只有 vc15，问题不大。后来同事的机器上是 VS2015，直接让他换成 vc14 的库路径，一切正常。还有一个隐蔽问题是 Debug 和 Release 的库名是一致的，但 2.4.13 的预编译包里 Debug 版本库文件后缀带 d，例如 opencv_core2413d.lib，一旦链接器匹配不到，就会提示 LNK1104 cannot open file，要去链接器输入那里把具体 lib 名加上相应的 d 后缀。

5. 常见问题排查：五条血泪踩坑记录

5.1 现象：GCC 编译报 CODEC_TYPE_ 未定义

这条在 Ubuntu 20.04、22.04 上几乎必现。GCC 11 以上版本对 2.4.13 源码里部分废弃变量做了更严格的兼容性处理，编译 modules/highgui 时会报类似error: ‘CODEC_TYPE_UNKNOWN’ was not declared in this scope的错误。

原因：2.4.13 的 videostab 模块里使用了 FFmpeg 旧版本定义的 codec type 枚举常量，新版本 FFmpeg 5.x 重构了这些符号。

解决：修改源码中对应位置，在报错文件顶部加上恢复宏定义：

#define CODEC_TYPE_UNKNOWN AVMEDIA_TYPE_UNKNOWN #define CODEC_TYPE_VIDEO AVMEDIA_TYPE_VIDEO #define CODEC_TYPE_AUDIO AVMEDIA_TYPE_AUDIO

有些人建议直接升级到 2.4.13 的 patch 版，但网上并没有官方补丁发布，还是手动改源码最靠谱。这个修改不会影响核心模块，放心加。如果你不想动源码，另一个办法是用 GCC 9 或更早版本编译，但系统自带 GCC 版本如果高于 10，还得自己装旧 GCC 再切工具链，改动面更大。

5.2 现象：CUDA 探测失败导致整体编译中止

CMake 配置阶段报CUDA_TOOLKIT_ROOT_DIR not found，或者直接提示找不到 nvcc，最后 cmake 失败退出。

原因：WITH_CUDA 默认开启，但新机器上往往没有安装完整 CUDA 工具链，CMake 探测不到就终止。

解决：没有 CUDA 需求的人，最直接的处理是编译参数里显式设置-D WITH_CUDA=OFF。如果确实需要 GPU 加速，就要把 CUDA 工具包版本控制在 9.0 以下，因为 2.4.13 只支持到当时的主流 CUDA 版本。我要强调的是，很多人只是存疑试一把，结果 CUDA 没配上反而把整个编译流程拖垮，这个开关不碰最稳。

5.3 现象：编译成功但 imshow 显示空白窗口

程序跑起来，imshow 窗口弹出来了，但是画面是灰色，或者一直无响应。

原因：highgui 模块链接的是 GTK2 还是 GTK3，以及是 x11 后端还是其他后端，都有影响。GTK3 环境下 2.4.13 的老代码在某些回调上不兼容，看起来就是窗口不刷新。

解决：确认编译时用的是 libgtk2.0-dev，不是 libgtk-3-dev：

apt list --installed | grep gtk

如果装的是 GTK3 库，CMake 检测默认倾向 GTK3，这时要显式设置-D WITH_GTK=ON -D GTK2_GTK_INCLUDE_PATH=...让 CMake 定位 GTK2。编译完成后查看 CMakeCache.txt 里 WITH_GTK 和 GTK2 的检测结果，确认没有走偏。

5.4 现象：链接报 LNK2038 mismatch detected for RuntimeLibrary

Windows 上 VS2019 编译项目，链接时报LNK2038: mismatch detected for RuntimeLibrary。

原因：项目使用的是 /MDd（动态调试运行时），而 OpenCV 预编译库默认对接的是 /MD（动态发布运行时），两者混在一起就报错。本质上是项目属性和 OpenCV 库编译时采用的运行时不一致产生的结果。

解决：在 VS 项目属性中把 C/C++ 代码生成里的运行库改成与 OpenCV 库匹配的选项，一般设成 /MD 或 /MDd 二选一。更规范的做法是创建两个配置：Debug 全链带 d 的 debug 库并配 /MDd，Release 链不带 d 的库并配 /MD。搜到网上说要改 stdafx.h 加宏的都是弯路，直接改属性就行。

5.5 现象：手写 vector 相关代码在 debug 模式下崩溃

Debug 构建的程序在使用 std::vector 或 cv::Mat 深拷贝时随机崩溃，Release 下却正常。

原因：CRT 版本不是唯一问题，OpenCV 2.4.13 预编译的 debug 库与 VS 2015 以上版本的迭代器调试模式（_ITERATOR_DEBUG_LEVEL）不匹配，导致容器迭代器越界时没有触发应有的检查机制，反而出现非法内存访问。

解决：一种做法是把预编译库替换为源码编译产物，保证工具集完全一致。另一种是简单粗暴，把 Debug 配置也切到 Release 的库文件上，牺牲调试能力换取稳定。我做项目时选择源码在目标 VS 版本下编译一遍，设备和工具链差异总是会以最恨的方式回报你。

6. 验证跑通：编写一个相貌检测 Demo 与版本验证清单

组装完成后，验证要从三个层面走通：核心库能载入、Python 绑定可用或者 C++ 项目能编译、图像处理链路能输出结果。我不会拿一张全黑图去跑，而是直接用 cascade 分类器检测人脸，一步到位。

先写一个 C++ 版本验证程序：

#include "opencv2/objdetect/objdetect.hpp" #include "opencv2/highgui/highgui.hpp" #include "opencv2/imgproc/imgproc.hpp" #include <iostream> using namespace cv; int main(int argc, char** argv) { CascadeClassifier face_cascade; if (!face_cascade.load("/usr/local/opencv2.4.13/share/OpenCV/haarcascades/haarcascade_frontalface_alt.xml")) { std::cout << "加载分类器失败" << std::endl; return -1; } Mat frame = imread("test.jpg", CV_LOAD_IMAGE_COLOR); if (frame.empty()) { std::cout << "图片读取失败" << std::endl; return -1; } std::vector<Rect> faces; Mat gray; cvtColor(frame, gray, CV_BGR2GRAY); equalizeHist(gray, gray); face_cascade.detectMultiScale(gray, faces, 1.1, 3, 0, Size(30, 30)); for (size_t i = 0; i < faces.size(); i++) { rectangle(frame, faces[i], Scalar(0, 0, 255), 2); } imwrite("output.jpg", frame); std::cout << "检测到 " << faces.size() << " 张人脸，结果已保存" << std::endl; return 0; }

代码逻辑说明：先加载 OpenCV 自带的 LBP 或 Haar 人脸检测分类器，路径要锚定到安装目录。然后把测试图转成灰度、直方图均衡化处理，再调 detectMultiScale 扫描出人脸矩形位置，画框后输出结果。如果这个程序能完整跑通，说明 core、imgproc、objdetect 三个核心模块都工作正常。

如果走 Python 路线，验证脚本更短：

python3 -c "import cv2; print(cv2.__version__)"

能打印出 2.4.13 就代表模块路径没配错。继续做个快速检测验证链路：

python3 -c " import cv2 img = cv2.imread('test.jpg') gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) face_cascade = cv2.CascadeClassifier('/usr/local/opencv2.4.13/share/OpenCV/haarcascades/haarcascade_frontalface_alt.xml') faces = face_cascade.detectMultiScale(gray, 1.1, 3) print('faces:', len(faces)) "

输出 faces 数量大于等于 1 才算通过，0 不一定是环境坏了，可能是图片本身角度问题，换一张正脸照再试。

完整跑通之后，我习惯做一个自检清单：cmake 配置阶段无致命错误、make 编译零 error、cv2 模块能导入且版本号对、C++ 程序能编译运行、图像输出文件非空。这套流程我从第一次编译到现在走了不下十遍，踩过的坑攒成了上面的五条排查记录。后来再装 2.4.13，我不管时间多紧都会强制跑一遍这个验证程序，不看到人脸框画出来就不算完事。版本回退这种事，重装三遍不如一次验证到位，希望这份安装笔记能帮到你。

本文还有配套的精品资源，点击获取