Ubuntu 20.04 下 OpenCV 4.4.0 离线编译与库文件排错

简介：面向 Windows 平台使用 VS2015 开发 OpenCV 4.4.0 的开发者，这份压缩包汇集了源码编译阶段所需的第三方依赖下载文件，以及编译后生成的 x64 动态库、静态库与配套头文件，可减少因网络受限、依赖缺失或版本不匹配造成的编译中断。对于需要配置工程、排查链接错误或复现编译环境的读者，可借此省去反复下载第三方依赖、处理 CMake 配置和核对库文件版本的环节。包内共 575 个文件，以 hpp、h 头文件为主体，辅以 cmake 构建脚本、xml 配置、dll/lib 库文件、exe 工具及许可证说明，压缩包约 156.61MB，目录覆盖依赖缓存、编译产物与开发接口，便于直接接入项目或对照检查。已有 563 人学习下载，适合希望快速搭建 OpenCV 4.4.0 开发环境、补齐 Intel IPP、FFmpeg、ADE 等依赖的中高级开发者参考使用。对于教学演示、课程实验与旧项目维护，也能提供可比对的编译产物与依赖清单。

1. 从一台离线编译机说起：opencv-4.4.0 源码包和库文件为什么总对不上

opencv-4.4.0 这套源码编译环境，真正让人翻车的往往不是 make，而是下载文件和生成的库文件对不上。某实验室的离线编译机里，源码包解压后 CMake 顺利跑完，一到 ippicv_2020 就卡住，后面虽然生成了 libopencv_videoio.so，却打不开视频，ffmpeg_version.cmake 的结果也像黑匣子。装不好时，编译能过，运行时报符号缺失，或者 Python 导入 cv2 直接失败。这套环境适合需要固定 4.4.0 版本、又要把下载文件和库文件一起归档的开发者；新手照着走能跑通，熟手重点看版本取舍和离线包放置。

2. 环境准备：Ubuntu 20.04 上给 opencv-4.4.0 配一套不打架的工具链

opencv-4.4.0 不是一个“装上最新工具链就完事”的版本。它处在旧版 OpenCV 4.x 的中间位置，系统里的 CMake、GCC、Python 和 FFmpeg 开发包只要有一个跨度太大，配置阶段就可能把 videoio、python3 这些模块自动降级。血泪经验是先把版本摊开看清楚，再决定装什么，不要一上来就make -j$(nproc)。我一般会把编译机和运行机分开看：编译机负责生成库文件，运行机只装必要的运行库；如果两边是同一台机器，更要把安装前缀和动态库路径提前规划好。

2.1 版本对照：CMake、GCC、Python 和 FFmpeg 开发包

先跑一组只读检查命令，不改系统，把当前环境摸清楚。下面的命令不会安装任何东西，输出结果直接决定后面要不要补包。

lsb_release -a # 看发行版版本，Ubuntu 18.04/20.04 更稳 uname -m # 看架构，x86_64 和 aarch64 的包名不一样 gcc --version | head -1 # GCC 7/9 对 4.4.0 比较友好 g++ --version | head -1 cmake --version | head -1 # 建议 3.10 以上，不要盲目追最新 pkg-config --modversion libavcodec 2>/dev/null || echo "libavcodec-dev missing" python3 --version # Python 3.x 即可，重点看开发头文件

这段命令的核心是确认三件事：系统架构、编译器大版本、FFmpeg 开发包是否存在。pkg-config --modversion libavcodec如果直接报 missing，说明libavcodec-dev没装，后面ffmpeg_version.cmake探测大概率不会通过。CMake 版本不是越高越好，太新的 CMake 对旧项目的策略检查会更严格，配置日志里容易出现一堆“Policy CMP”警告；能稳定配置、能生成 Makefile 就够了。

2.2 目录规划：源码、构建目录和离线缓存分开放

我习惯把源码目录、构建目录、下载缓存目录分开。源码目录只解压，不改；构建目录放 CMake 生成的文件；下载缓存目录单独放 ippicv_2020 这类离线包，迁移机器时整目录拷走，不用重新找包。下面命令里的压缩包名按你手头的实际文件替换，不要照抄一个不存在的路径。

mkdir -p $HOME/src/opencv-4.4.0 \ $HOME/src/opencv-build \ $HOME/src/opencv-download tar -xzf $HOME/Downloads/opencv-4.4.0.tar.gz -C $HOME/src

opencv-4.4.0是源码目录，opencv-build是构建目录，opencv-download是 CMake 下载第三方包时的缓存目录。源码目录里不要直接cmake .，否则生成的CMakeCache.txt、CMakeFiles会和源码混在一起，下次换参数配置时清都不好清。构建目录可以整个删掉重来，源码目录尽量保持干净，这样出问题能判断是源码损坏还是配置参数写错。

如果还需要 contrib 模块，源码包也按同样方式解压到$HOME/src/opencv_contrib-4.4.0，后面 CMake 参数里再加-DOPENCV_EXTRA_MODULES_PATH。不需要 contrib 就不要开，模块越多，编译时间和依赖冲突越多。

2.3 依赖安装：一条命令补齐编译期和运行期库

Ubuntu 20.04 上我一般用下面这组包。不同镜像源包名略有差异，缺哪个补哪个，不要一次性把能搜到的包全装上。

sudo apt update sudo apt install -y \ build-essential cmake pkg-config \ libjpeg-dev libpng-dev libtiff-dev \ libavcodec-dev libavformat-dev libswscale-dev libavutil-dev \ libv4l-dev libdc1394-22-dev \ libgtk-3-dev \ libtbb2 libtbb-dev \ python3-dev python3-numpy

build-essential提供 gcc、g++、make；cmake和pkg-config是配置阶段的基础工具；libjpeg-dev、libpng-dev、libtiff-dev负责图像编解码；libavcodec-dev、libavformat-dev、libswscale-dev、libavutil-dev是 FFmpeg 开发包，直接决定 videoio 能不能读视频；libgtk-3-dev给 highgui 提供窗口能力；libtbb2和libtbb-dev是并行库；python3-dev、python3-numpy用于 Python 绑定。

提示：如果这台机器只做后台图像处理，不需要弹窗显示，可以少装libgtk-3-dev，配置时加-DWITH_GTK=OFF。但视频读取依赖的 FFmpeg 开发包不要省，省了后面ffmpeg_version.cmake探测失败，还得回头补。

装完再跑一次pkg-config --modversion libavcodec libavformat libavutil libswscale，四个都输出版本号才算齐。只输出一个或两个，说明开发包没装全，不要急着进 CMake 配置。

3. 配置阶段：把 ippicv_2020 和 ffmpeg_version.cmake 按 CMake 的规则喂进去

配置阶段是 opencv-4.4.0 最容易出玄学的地方。CMake 会去下载 ippicv_2020，会探测系统 FFmpeg 并生成ffmpeg_version.cmake一类中间结果，还会判断 Python 绑定要不要编译。网络不通时，下载失败不一定立刻停，有时会降级继续，最后生成的库文件少功能，运行时才发现视频打不开。我的做法是先把离线包和 FFmpeg 探测结果确认一遍，再让 CMake 一次配置到位。

3.1 先读 ippicv.cmake，再决定离线包放哪

不要凭记忆猜 ippicv_2020 的压缩包名和存放路径。源码里3rdparty/ippicv/ippicv.cmake写了文件名、校验值和缓存目录，先读它。

cd $HOME/src/opencv-4.4.0 grep -n "ippicv" 3rdparty/ippicv/ippicv.cmake | head -20

这条命令把ippicv.cmake里和 ippicv 相关的行打出来。重点看FILENAME、HASH、DESTINATION_DIR这几个字段，压缩包名要和FILENAME一致，不要自己改成ippicv_2020.tgz这种短名。常见做法是把离线包放进OPENCV_DOWNLOAD_PATH指定的缓存目录，再重新跑 CMake，让下载器先命中缓存。

mkdir -p $HOME/src/opencv-download cp /path/to/ippicv_2020_*.tgz $HOME/src/opencv-download/

OPENCV_DOWNLOAD_PATH是给 CMake 下载器用的缓存根目录，cp的目标文件名保持原样。配置时如果日志仍然显示去远程下载，不要反复删构建目录，先看日志里打印的DESTINATION_DIR，把包放到那个目录再试。我一般把$HOME/src/opencv-download整个目录归档，换机器时直接恢复，ippicv_2020 就不用再找。

注意：如果暂时不需要 IPP 加速，可以在配置时加-DWITH_IPP=OFF先让编译跑通，但要清楚这是功能取舍，不是问题消失。后面要启用 IPP，还是得把 ippicv_2020 的缓存路径配对。

3.2 CMake 参数取舍：WITH_FFMPEG、BUILD_LIST 和安装前缀

下面这组参数是我在 opencv-4.4.0 上比较常用的配置。它没有把模块开满，而是保留 core、imgproc、imgcodecs、videoio、highgui 和 Python 绑定，够做图像读取、视频读取和基础处理。

cd $HOME/src/opencv-build cmake -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=/usr/local \ -DOPENCV_GENERATE_PKGCONFIG=ON \ -DWITH_FFMPEG=ON \ -DWITH_IPP=ON \ -DBUILD_LIST=core,imgproc,imgcodecs,videoio,highgui \ -DBUILD_opencv_python3=ON \ -DBUILD_TESTS=OFF \ -DBUILD_PERF_TESTS=OFF \ -DOPENCV_DOWNLOAD_PATH=$HOME/src/opencv-download \ -DPYTHON3_EXECUTABLE=$(which python3) \ ../opencv-4.4.0

CMAKE_BUILD_TYPE=Release生成优化后的库，日常部署不要用 Debug；CMAKE_INSTALL_PREFIX=/usr/local是安装前缀，make install后库文件进/usr/local/lib，头文件进/usr/local/include/opencv4；OPENCV_GENERATE_PKGCONFIG=ON会生成opencv4.pc，后面pkg-config验证靠它；WITH_FFMPEG=ON打开视频读写；WITH_IPP=ON打开 IPP 加速，前提是 ippicv_2020 能命中缓存；BUILD_LIST只编译指定模块，能省时间，但 videoio 依赖 imgproc、imgcodecs，列表里少一个就可能在链接阶段报错；BUILD_opencv_python3=ON生成 Python 绑定；PYTHON3_EXECUTABLE明确指定解释器，避免 CMake 找到另一个 Python。

3.3 看配置输出：哪些 YES 是真的，哪些是自动降级

CMake 跑完后不要只看最后一行有没有 “Configuring done”。先查缓存里的关键开关，再看终端输出里 Video I/O 和 Python 3 的状态。

grep -E "WITH_FFMPEG|WITH_IPP|BUILD_opencv_python3|PYTHON3_EXECUTABLE" CMakeCache.txt

CMakeCache.txt里能看到你传进去的参数有没有被改写。WITH_FFMPEG是 ON，不代表 FFmpeg 一定被找到；还要看配置输出里 “Video I/O” 后面是不是 FFMPEG。WITH_IPP是 ON，但 ippicv_2020 没命中缓存时，配置可能继续走，最后 IPP 实际没启用。PYTHON3_EXECUTABLE要指向你真正要用的那个 Python，不是系统里随便一个。

find . -name "ffmpeg_version.cmake" -o -name "OpenCVConfig.cmake" | head

ffmpeg_version.cmake是 FFmpeg 探测过程的中间结果，找到它之后可以看里面记录的版本信息。如果这个文件没生成，或者生成后内容为空，优先检查libavcodec-dev等开发包和pkg-config路径。OpenCVConfig.cmake生成在构建目录里，说明配置阶段至少走完了，后面编译才有基础。

配置输出里出现 “IPPICV: Download: ippicv_2020” 并且一直停住，说明缓存没命中，回到 3.1 检查文件名和目录。出现 “FFMPEG: NO” 但WITH_FFMPEG=ON，说明系统开发包没装全，或者pkg-config找不到.pc文件。出现 Python 3 的NO，先看PYTHON3_EXECUTABLE和python3-dev，不要直接怀疑 OpenCV 源码。

4. 编译与生成库文件：从 build/lib 到 /usr/local/lib 的落地过程

配置通过后，编译阶段主要看内存和并行度。opencv-4.4.0 的模块不算少，make -j$(nproc)在小内存机器上很容易被 OOM 杀掉，表现是c++: fatal error: Killed signal terminated program cc1plus。我一般先-j2跑一遍，确认没有编译错误，再决定要不要加并行。生成库文件后，build/lib里是一套，make install后/usr/local/lib里是另一套，两套要对得上。

4.1 并行编译：make -j 不是越大越好

先进入构建目录，用较低并行度编译。下面命令里的-j2是保守值，内存充足的机器可以加到-j4，但不要一上来就按 CPU 核数拉满。

cd $HOME/src/opencv-build make -j2

make -j2表示同时跑两个编译任务。OpenCV 的 C++ 模板编译很吃内存，每个任务可能要占不少 RAM，核数多不代表内存够。编译中途出现Killed，不是代码错，是系统内存不足把编译器杀了。解决方式是降到-j1，或者临时加 swap，或者只编译BUILD_LIST里的核心模块。编译日志里出现某个模块 skip，不一定是失败，可能是依赖没开；但出现Error 1就要停下来看第一个报错，不要往后翻。

如果只改了一个模块，可以进对应子目录单独make，但第一次完整编译不建议跳步。生成库文件之前，确保build/lib目录存在，后面用find查库文件才有意义。

4.2 生成库文件清单：so、a、pkg-config 和 Python 绑定

编译完成后先别急着安装，在build/lib里确认生成的库文件。下面命令列出动态库和静态库，名字和版本号能对上，说明编译产物是完整的。

find $HOME/src/opencv-build/lib -maxdepth 1 \ \( -name "libopencv_*.so*" -o -name "libopencv_*.a" \) | sort

输出里应该能看到libopencv_core.so.4.4.0、libopencv_imgproc.so.4.4.0、libopencv_imgcodecs.so.4.4.0、libopencv_videoio.so.4.4.0、libopencv_highgui.so.4.4.0这些核心库。.so.4.4.0是实际库文件，.so.4.4和.so通常是软链接。只看到.so没有版本号，或者某个模块只有.a没有.so，要回看 CMake 配置里BUILD_SHARED_LIBS有没有被改过。

opencv4.pc不一定在lib下，可能在build/unix-install或安装后的lib/pkgconfig里。用find $HOME/src/opencv-build -name "opencv4.pc"确认。Python 绑定会生成cv2*.so，路径和 Python 版本有关，安装后以import cv2为准。

4.3 安装与动态库路径：ldconfig 和 PKG_CONFIG_PATH

确认库文件存在后，执行安装。安装前缀是/usr/local，需要写权限，所以用sudo。

cd $HOME/src/opencv-build sudo make install sudo ldconfig

make install把头文件、库文件、opencv4.pc和 Python 绑定复制到安装前缀下；ldconfig刷新动态链接器缓存，让运行程序能找到/usr/local/lib下的新库。没有ldconfig，编译能过，运行时报error while loading shared libraries: libopencv_core.so.4.4。

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH pkg-config --modversion opencv4 pkg-config --cflags --libs opencv4

PKG_CONFIG_PATH告诉pkg-config去哪里找opencv4.pc。--modversion应该输出4.4.0，--cflags --libs应该输出头文件路径和-lopencv_*链接参数。如果--modversion输出的是系统旧版本，说明PKG_CONFIG_PATH顺序不对，或者系统里另有一个opencv4.pc排在前面。

提示：/usr/local/lib不一定在所有发行版的默认动态库搜索路径里。ldconfig之后仍然找不到库，检查/etc/ld.so.conf.d/下有没有包含/usr/local/lib的配置，不要直接改系统库文件。

5. 避坑与排查：opencv-4.4.0 编译现场最常见的五类翻车

这一章按“现象 → 原因 → 解决”记录。每一条都是我在离线编译机或旧系统升级现场遇到的真实类型，不是理论清单。出现问题时先定位到哪一类，再动手改，不要一上来就删构建目录重装系统。

5.1 ippicv_2020 一直下载失败

现象：CMake 配置停在IPPICV: Download: ippicv_2020，终端长时间无输出，最后报下载超时或校验失败。删掉构建目录重来，还是卡在同一行。

原因：ippicv.cmake里登记的文件名和缓存目录没有对上。离线包可能被改了名，或者放进了OPENCV_DOWNLOAD_PATH的子目录，而 CMake 实际去另一个DESTINATION_DIR找。还有一种情况是压缩包下载不完整，校验值对不上，CMake 认为缓存无效。

解决：回到源码目录读ippicv.cmake，确认FILENAME和HASH，把离线包按原文件名放到配置日志打印的缓存目录。重新配置前先清掉CMakeCache.txt里和 IPPICV 相关的缓存项，或者直接新建构建目录。

cd $HOME/src/opencv-4.4.0 grep -n "ippicv" 3rdparty/ippicv/ippicv.cmake | head -20 find $HOME/src/opencv-download -maxdepth 2 -iname "ippicv*"

如果只是想让编译先跑通，可以加-DWITH_IPP=OFF，但要记住这是临时取舍。后面启用 IPP 时，还是要把缓存目录配对。

5.2 ffmpeg_version.cmake 探测不到或版本过高

现象：配置输出里Video I/O显示NO或FFMPEG: NO，build目录里找不到ffmpeg_version.cmake；或者找到了文件，但编译videoio时出现大量 FFmpeg API 相关报错。

原因：系统没装libavcodec-dev、libavformat-dev、libswscale-dev、libavutil-dev，pkg-config找不到.pc文件。另一种原因是系统 FFmpeg 版本太新，opencv-4.4.0 的 videoio 代码对不上新 API，探测阶段能过，编译阶段失败。

解决：先补开发包，再用pkg-config确认版本。不要在没有开发包的情况下反复开WITH_FFMPEG=ON。

sudo apt install -y libavcodec-dev libavformat-dev libswscale-dev libavutil-dev pkg-config --modversion libavcodec libavformat libavutil libswscale

四个包都输出版本号后，新建构建目录重新配置。如果系统 FFmpeg 版本确实太高，优先用发行版仓库里的开发包，不要硬追最新主分支；必要时先只编译core,imgproc,imgcodecs，确认工具链没问题，再单独处理videoio。ffmpeg_version.cmake是探测结果，不是拿来手改的配置文件。

5.3 CMake 找到 Python 但 make install 后 import cv2 失败

现象：配置输出里 Python 3 是 YES，make install也完成了，但python3 -c "import cv2"报ModuleNotFoundError: No module named 'cv2'。

原因：CMake 找到的 Python 解释器和实际使用的 Python 不是同一个，或者 Python 绑定的安装路径不在sys.path里。系统里可能有多个 Python，python3指向其中一个，PYTHON3_EXECUTABLE却指到另一个。

解决：配置时明确指定解释器，安装后检查sys.path和cv2的实际位置。

python3 -c "import sys; print(sys.executable); print(sys.path)" find /usr/local -name "cv2*.so" 2>/dev/null | head

sys.executable要和 CMake 里的PYTHON3_EXECUTABLE一致。找到cv2*.so后，把所在目录加进PYTHONPATH，或者重新用正确的 Python 配置编译。不要直接把.so复制到随便一个目录，ABI 对不上会报另一个错。

5.4 链接时提示 undefined reference 或 ABI 冲突

现象：编译 demo 时出现undefined reference to cv::...，或者运行时报symbol lookup error，又或者ldd demo看到链接到了系统里另一个旧版 OpenCV。

原因：pkg-config找到的是旧版opencv4.pc，链接参数指向旧库；或者LD_LIBRARY_PATH里有另一套 OpenCV，运行时先加载了旧库。ABI 冲突通常发生在系统包和源码安装混用的时候。

解决：先看pkg-config输出了什么，再看运行时实际加载了哪个库。

pkg-config --modversion opencv4 pkg-config --cflags --libs opencv4 ldd ./demo | grep opencv

--modversion必须是4.4.0，ldd里的路径要指向/usr/local/lib下的 4.4.0 库。如果指向系统旧路径，调整PKG_CONFIG_PATH顺序，确认ldconfig已执行。不要把旧版 OpenCV 的头文件和 4.4.0 的库混在一起编译，头文件和库版本不一致，链接阶段就会翻车。

5.5 编译到一半内存被 OOM 杀掉

现象：make跑到某个模块突然停住，日志里出现c++: fatal error: Killed signal terminated program cc1plus，终端没有明显的语法错误。

原因：并行编译任务太多，每个 C++ 编译进程占用内存较大，系统内存不足触发 OOM Killer。-j$(nproc)在核多内存小的机器上特别容易出问题。

解决：降并行度，或者加 swap，或者精简BUILD_LIST。

cd $HOME/src/opencv-build make -j1

先用-j1确认能完整编译，再考虑-j2。如果机器内存确实紧张，配置时只保留core,imgproc,imgcodecs,videoio，把highgui和 Python 绑定放到另一台机器上编。OOM 不是代码错误，不要反复重装依赖。

6. 装完怎么验证跑通：用 pkg-config 和一段视频读取代码把库文件验到底

装完不等于跑通。我一般分三层验证：第一层查pkg-config版本，第二层编译一个 C++ demo 看链接，第三层用VideoCapture读一段小视频，确认 FFmpeg 后端真的工作。三层都过，才说明build/lib里生成的库文件和/usr/local/lib里安装的库文件对得上。

先写一个尽量小的 C++ 验证文件，打印版本和编译信息，再打开视频读一帧。视频文件换成手头能播放的小文件，不要用摄像头，摄像头还多一层权限问题。

#include <opencv2/opencv.hpp> #include <iostream> int main() { std::cout << "OpenCV: " << CV_VERSION << std::endl; std::cout << cv::getBuildInformation() << std::endl; // 看 FFMPEG 是否为 YES cv::VideoCapture cap("test.mp4"); // 换成手头的小视频 if (!cap.isOpened()) { std::cerr << "video open failed" << std::endl; return 1; } cv::Mat frame; cap >> frame; if (frame.empty()) { std::cerr << "empty frame" << std::endl; return 2; } std::cout << "frame: " << frame.cols << "x" << frame.rows << std::endl; return 0; }

编译命令用pkg-config取头文件和链接参数，不要手写一长串-lopencv_*。手写容易漏库，也容易把旧路径带进来。

g++ demo.cpp -o demo $(pkg-config --cflags --libs opencv4) ./demo | grep -E "OpenCV:|FFMPEG|frame:"

pkg-config --cflags --libs opencv4输出-I/usr/local/include/opencv4和对应的-L/usr/local/lib -lopencv_*。运行输出里OpenCV:应该是4.4.0，FFMPEG应该是YES，最后打印出视频帧的宽高。如果VideoCapture打不开，但OpenCV:版本对，优先查 FFmpeg 开发包和ffmpeg_version.cmake，不要怀疑视频文件本身。

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