简介这是一份在 Ubuntu 21.04 64 位系统下预先编译完成的 OpenCV 4.5.5 开发包面向需要直接使用 C 接口的开发者免去从源码编译的繁琐过程解压后即可集成到项目。资源采用 7z 格式压缩共 1426 个文件大小约 49.18MB。文件组成以头文件、动态库和示例源码为主489 个 hpp 负责声明接口55 个 so 提供编译好的功能模块335 个 cpp 给出具体用法另有 Python 脚本、xml/yml 模型配置、图片素材和 prototxt 等便于同时开展图像处理、深度学习与相机标定方面的开发。压缩包内带 CMake 配置目录在工程中只需将 OpenCV_DIR 指向对应路径再执行 find_package(OpenCV REQUIRED) 即可完成链接同时提供命令行小工具用于检查安装是否正常。目前已有 754 人学习下载。对于希望快速搭建开发环境、避免版本兼容性问题的 Linux 用户这是一份开箱即用的省心资源。1. 解压即用的 OpenCV 4.5.5它省掉的是几小时编译省不掉的是几个边界OpenCV 4.5.5 的 Linux 预编译包解压以后改一下库路径再用 CMake 指一下 OpenCV_DIRC 代码就能直接编译运行。它的价值不在安装快而在于你不需要为验证一个想法先把编译环境从头陪跑一遍。适合的场景很典型新装了一台机器要跑老项目或者手头同时有几个版本想快速做对比。但“解压直接可以使用”有前提——x86_64 架构、系统运行库不能太老、不带 CUDA 和 contrib。这篇笔记就把这些前提、路径和坑一次讲清楚。2. 为什么选预编译版而不是源码编译4.5.5 的构建成本与适用边界2.1 源码编译 OpenCV 4.5.5 要付出的五项成本先说结论源码编译没有想象中难但它的成本不在敲那几条 cmake 命令而在“一次通过”的概率。OpenCV 4.5.5 作为 4.5 系列尾部版本API 已经比较收敛很多存量项目就是按这个版本写的imread、VideoCapture和CascadeClassifier用法所以大家才会专门去找这个版本的预编译文件。第一项成本是 CMake 配置。一个常见的配置命令长这样cmake -S opencv-4.5.5 -B build \ -DCMAKE_BUILD_TYPERelease \ -DBUILD_EXAMPLESOFF \ -DBUILD_TESTSOFF \ -DBUILD_opencv_python3OFF这段命令本身不复杂但参数组合决定了后续所有行为。BUILD_EXAMPLES和BUILD_TESTS不开能省掉不少编译量BUILD_opencv_python3关掉是不想被 Python 绑定拖住。问题在于你还要评估自己到底需要哪些模块一旦某个模块编译失败整个构建可能中断而排查失败原因往往比编译本身更费时间。第二项成本是依赖检测。OpenCV 的可选依赖有一长串图像编解码要用 libjpeg、libpng、zlib视频要碰 FFmpegGUI 要碰 GTK。源码编译时CMake 会探测这些库在不在系统里缺了它就自动把对应功能关掉。最典型的情况是编完了发现imread只能读 BMP因为 libpng 没装PNG/JPG 支持在配置阶段就被悄悄关闭了。这个问题在预编译包里不太会出现因为打包者通常已经把这些依赖链处理好了。第三项成本是编译时长和机器占用。在 8 核 16G 的机器上Release 模式只编核心模块顺利的话大概在一刻钟到半小时之间如果模块开得多或者磁盘慢时间会翻倍。编译期间内存和 CPU 都会被拉满这时候你没法在这台机器上干别的。对只想先跑通一个模板匹配 demo 的人来说这个等待完全没有必要。第四项成本是失败重来。编译过程中最常见的翻车点是从网上下载第三方源码超时或者系统里某个库的版本和 OpenCV 4.5.5 不兼容报错信息却很隐晦。我见过某开发者为了编一个带 contrib 的版本连续折腾了两天最后发现是某个依赖库的 pkg-config 文件路径写错了。这种问题在源码编译场景里很常见而它对业务代码毫无贡献。第五项成本是后续维护。源码编译默认装到/usr/local之后你想换 4.9 版本得要重新编一次还要记得make uninstall或者手动清理很难做到两个版本干净共存。预编译包放在/opt下目录一删就回到原状后悔药是现成的。这也是很多人最终转向预编译文件的关键理由。2.2 预编译包能做什么、不能做什么一张表做选型“解压直接可以使用”这句话不能理解成“任何 Linux 上都能跑”。预编译包是在某个特定的发行版、特定编译器版本、特定 CPU 架构上构建出来的它自带的前提条件你没法从文件名上看出来。我的经验是先看一张能力对照表再决定要不要用。能力项预编译包通常情况需要源码编译的情况x86_64 CPU 基础模块通常包含 core/imgproc/imgcodecs/highgui 等需要裁剪体积、只留特定模块CUDA GPU 加速不带链接期没有对应符号必须自己配 CUDA 环境编译contrib 扩展模块通常不带需要 aruco、ximgproc、optflow 等Python 绑定打包版本和你的 Python 大概率对不上按目标 Python 版本重新构建交叉编译 / ARM 平台基本不通用必须针对目标硬件编译这张表的核心判断标准是你的项目如果只依赖 OpenCV 标准模块预编译包是合理的如果主力是dnn加 GPU 推理或者要往嵌入式板子上搬那就别省这一步。4.5.5 本身的 API 在老项目里出现频率很高这也是它被做成预编译包后仍然值得用的原因。另外要提醒一句预编译包通常不带 contrib也不带 CUDA 工具链的符号。就算你后来装了 CUDA预编译的.so也不会因此获得 GPU 能力因为那是在编译期决定并写进库文件里的。想验证包里到底有哪些模块后面第 3 章给的探针程序会顺带解决。3. 解压后的目录和可用性探测先确认它真的能跑再写业务代码3.1 认清 bin/include/lib/share 的职责把包放到 /opt 下拿到压缩包第一步不是解压到当前目录而是先规划放哪。我一般会把它放到/opt下并按版本号重命名而不是解压到/usr/local或者项目源码目录里。原因有两个一是/opt就是给这类独立软件包准备的不会和发行版自带的 OpenCV 抢文件二是后面做多版本切换时/opt/opencv455和/opt/opencv49这类目录天然隔离删旧换新只需一条rm -rf这是真正的后悔药。但要注意用法mkdir -p /opt tar -xvzf opencv-4.5.5-linux.tar.gz -C /opt mv /opt/opencv-4.5.5 /opt/opencv455-C指定了解压目标目录解压出来如果自带版本号目录名就直接用mv改成一个不带点和横杠的名字省得后续在脚本里转义。解压完成后不要急着写代码先花两分钟把目录结构看明白因为后面所有编译参数都依赖这几个路径。bin/可执行工具最有用的是opencv_version用来确认当前库的真实版本。include/opencv4/头文件根目录C 代码里写#include opencv2/core.hpp对应的是这个目录下的opencv2/core.hpp。lib/核心.so文件所在位置。通常能看到libopencv_core.so这种无版本软链和libopencv_core.so.4.5.5这种真实文件。share/OpenCV/或者lib/cmake/opencv4/存放OpenCVConfig.cmake的位置这是 CMake 找到 4.5.5 的入口。lib/pkgconfig/有的话会放opencv4.pc给 pkg-config 用。我建议你先执行下面两条命令把关键文件的位置确定下来而不是凭记忆写死find /opt/opencv455 -name OpenCVConfig.cmake find /opt/opencv455 -name *.pc第一条的输出会告诉你 CMake 配置文件的真实路径第二条会告诉你 pkg-config 文件是否存在。不同打包者做预编译包的习惯不一样有的会把 cmake 文件放在share/OpenCV下有的放在lib/cmake/opencv4下所以“路径不要靠猜”这句话在这里特别值钱。头文件路径是include/opencv4而不是include这一个层级差很容易让编译期翻车。3.2 两条最小验证命令opencv_version 和一段探针代码很多人解压完只看了一眼目录名就开写结果编译时报一堆头文件找不到其实一个opencv_version就能排除掉一半问题。先看它能不能跑/opt/opencv455/bin/opencv_version正常情况下会输出4.5.5。如果这条命令报缺库说明LD_LIBRARY_PATH还没指到/opt/opencv455/lib先去设一下再回来。我一般会顺手用ldd看一眼它实际加载了哪个路径下的libopencv_core.soexport LD_LIBRARY_PATH/opt/opencv455/lib:$LD_LIBRARY_PATH ldd /opt/opencv455/bin/opencv_version | grep opencvldd输出里如果出现了多个 OpenCV 库的路径说明系统里还有其他版本在干扰这个问题后面第 5 章会专门讲。确认版本命令能跑之后再写一段探针代码验证 C 接口和图像编解码真的可用。我习惯用imencode而不是imread因为imread需要一张现成的图片文件而imencode直接生成一张纯色图并编码成 PNG一步就能测完 core 和 imgcodecs 两条链路。#include opencv2/core.hpp #include opencv2/imgcodecs.hpp #include iostream #include vector int main() { // CV_VERSION 是编译期宏直接反映当前头文件版本 std::cout OpenCV CV_VERSION std::endl; // 生成 64x64 纯色图并编码成 PNG验证 imgcodecs 插件链 cv::Mat img(64, 64, CV_8UC3, cv::Scalar(0, 255, 0)); std::vectorunsigned char png; bool ok cv::imencode(.png, img, png); std::cout encode_png ok bytes png.size() std::endl; return ok ? 0 : 1; }编译并运行这段代码export LD_LIBRARY_PATH/opt/opencv455/lib:$LD_LIBRARY_PATH g probe.cpp -o probe \ -I/opt/opencv455/include/opencv4 \ -L/opt/opencv455/lib \ -lopencv_core -lopencv_imgcodecs ./probe-I指定头文件搜索路径注意尾部的opencv4不能省略-L指定库搜索路径-lopencv_core会去lib目录里找libopencv_core.so。链接顺序这里也有讲究imgcodecs依赖core所以它必须写在core的前面。程序输出OpenCV 4.5.5并且encode_png1说明这个包的核心功能是完整的可以继续往下接工程。4. 把 4.5.5 接进 C 工程CMake 的 find_package 和裸 g 哪个更适合你4.1 CMake 路线OpenCV_DIR 指向哪里find_package 才不会找错版本在 C 工程里接预编译 OpenCV最不容易出错的方式是 CMake。核心思想是让find_package(OpenCV)找到解压目录里的OpenCVConfig.cmake而不是让它在系统路径里瞎逛。写一个最小 CMakeListscmake_minimum_required(VERSION 3.16) project(opencv455_probe) # 如果命令行没有通过 -D 指定 OpenCV_DIR就使用默认的预编译包路径 if(NOT DEFINED OpenCV_DIR) set(OpenCV_DIR /opt/opencv455/lib/cmake/opencv4) endif() find_package(OpenCV REQUIRED) message(STATUS Found OpenCV ${OpenCV_VERSION}) add_executable(probe_cmake main.cpp) target_include_directories(probe_cmake PRIVATE ${OpenCV_INCLUDE_DIRS}) target_link_libraries(probe_cmake PRIVATE ${OpenCV_LIBS})这个文件里最关键的是if(NOT DEFINED OpenCV_DIR)包裹的默认路径。写成这样命令行带上-DOpenCV_DIR...时能覆盖默认值不写的话就自动落到/opt/opencv455/lib/cmake/opencv4。如果没有这层保护直接在 CMakeLists 里写死set(OpenCV_DIR /opt/opencv455/lib/cmake/opencv4)CMake 里普通变量会优先于缓存变量命令行传参反而失效这是新手常踩的一个玄学点。配置和构建命令如下cmake -S . -B build -DOpenCV_DIR/opt/opencv455/lib/cmake/opencv4 cmake --build build-S .指定源码目录-B build指定构建目录-DOpenCV_DIR告诉 CMake 去哪找配置。构建成功后运行./build/probe_cmake输出应该和第 3 章探针一致。这里有一个我必须强调的坑CMake 会缓存变量。如果你第一次把OpenCV_DIR指错了路径比如指到了一个没用的目录find_package报错然后你改成正确的路径重新执行同样的cmake命令它仍然可能读缓存里的旧值。最干脆的解决方式是删掉build目录重新配置或者手动删掉build/CMakeCache.txt。不要在新手群里反复问为什么改了没用先把缓存清了再说。${OpenCV_LIBS}这个变量比较特殊它展开后是一长串库的绝对路径直接传给target_link_libraries就行。如果包是带opencv_world的单库形式它就是那一个库如果是模块化细分库形式展开后是core/imgproc/imgcodecs/highgui等一长串。不管哪种形式你都不需要自己去写-l参数了这正是 CMake 路线的最大价值。4.2 裸 g 路线-I、-L、-l 与 pkg-config 的取舍CMake 虽好但有些项目就是一个单文件测试程序不值得为了它建目录结构。这时候用裸 g 反而更直观。如果解压包里带了 pkg-config 文件最简单的方式export PKG_CONFIG_PATH/opt/opencv455/lib/pkgconfig:$PKG_CONFIG_PATH g main.cpp -o demo $(pkg-config --cflags --libs opencv4)pkg-config --cflags --libs opencv4会自动展开成-I/opt/opencv455/include/opencv4 -L/opt/opencv455/lib -lopencv_core ...省事省得干净。但它有一个前提.pc文件里写死的前缀路径必须是/opt/opencv455。如果你把解压目录移动了.pc文件并不会跟着智能变更得手工改里面的prefix行否则pkg-config输出的路径全是错的。没有.pc文件也别慌直接写显式参数g main.cpp -o demo \ -I/opt/opencv455/include/opencv4 \ -L/opt/opencv455/lib \ -lopencv_core -lopencv_imgproc -lopencv_imgcodecs -lopencv_highgui \ -Wl,-rpath,/opt/opencv455/lib这段命令的写法是有顺序讲究的。-l参数按依赖层级从高阶到低阶排列highgui依赖imgcodecs和imgprocimgcodecs和imgproc依赖core所以安排成imgcodecs -lopencv_imgproc -lopencv_core。如果你把-lopencv_core放在最前面GNU 链接器在处理静态库时可能报 undefined reference虽然共享库通常能容忍但养成正确顺序习惯能少踩很多坑。-Wl,-rpath,/opt/opencv455/lib是把运行时的库搜索路径直接写进可执行文件里。加了它运行./demo时就不需要手动export LD_LIBRARY_PATH这对部署到固定路径的机器特别友好。它的代价是路径被写死了一旦你把包挪走这个 rpath 会失效且不会报错提示。所以我的建议是开发机用LD_LIBRARY_PATH灵活切换部署机或交付给别人的程序用-Wl,-rpath写死两种方式各有各的适用场景。如果你想把裸 g 命令沉淀成可复用的东西写进 Makefile 是最自然的做法。把-I参数放进CXXFLAGS把-L和-Wl,-rpath放进LDFLAGS把-l参数放进LDLIBS后续只需要make demo一条命令。这一步虽然简单但能让“解压即用”的体验延续到每一次编译。5. “解压即用”常见避坑5 个翻车现场的现象、原因和修补5.1 编译链接都过了运行却报 libopencv_core.so.4.5.5 找不到这是最普遍的一个坑g 编译没报错链接也没报错但一运行就提示libopencv_core.so.4.5.5: cannot open shared object file。现象出现的原因其实很清晰。链接阶段你能通过-L找到库是因为编译命令里有这个路径但运行时找库的是系统动态链接器它默认只搜/usr/lib、/lib等系统目录不会因为你编译时用了-L就记住这个路径。把两者混为一谈是理解“链接”和“运行”两个阶段最常见的误区。解决方式有三种按推荐程度排。第一种是临时的export LD_LIBRARY_PATH/opt/opencv455/lib:$LD_LIBRARY_PATH只对当前终端会话有效。第二种是永久的但只在当前用户生效写进~/.bashrc。第三种是写进可执行文件编译时加-Wl,-rpath,/opt/opencv455/lib。我推荐开发阶段用第一种交付阶段用第三种第二种会把多版本切换变成灾难因为.bashrc里堆多了 export 之后你自己都记不清当前优先加载的是哪一版。5.2 undefined reference to cv::imread头文件与库不是同一个构建编译时报undefined reference to cv::imread或者一堆cv::Mat相关的符号找不到是典型的“头文件一套、库一套”问题。原因分两类。一类是字面路径混搭-I指向了/opt/opencv455/include/opencv4但-L和-l链接的却是系统/usr/lib下另一个 OpenCV 版本的库头文件声明了 4.5.5 的接口库文件里却没有对应符号。另一类更隐蔽GCC 的 C ABI 有两种模式如果预编译包是用-D_GLIBCXX_USE_CXX11_ABI0构建的而你用默认 ABI 编译库里的符号名会多一个B后缀或缺少对应修饰链接期直接找不到。解决第一步是确认符号到底在哪个库。用nm -D /opt/opencv455/lib/libopencv_imgcodecs.so.4.5.5 | grep imread如果能输出符号名说明库本身没问题问题在头文件和库的组合路径上。第二步是检查-I和-L是否都来自/opt/opencv455不要一个用 4.5.5 一个用系统默认版。第三步是如果符号名对不上就去看预编译包文档里有没有标注 ABI 模式通常做法是换一个与现代工具链兼容的包。5.3 GLIBCXX_3.4.29 not found预编译包的编译环境比你的系统新运行程序时报GLIBCXX_3.4.29 not found而opencv_version却能正常跑这个现象一开始会让人非常困惑。原因是预编译包里的某些.so尤其是 videoio 这类依赖较多外部库的模块是用比你当前系统更新的 GCC 编译的。它在 ELF 里记录了需要的新版本GLIBCXX符号你的系统运行库太旧提供不了。opencv_version能跑是因为这个工具链接的依赖少没踩到那部分新符号一旦你的代码链接到 videoio 或 dnn就露出了藏着的旧包袱。解决时不要试图绕过去。先定位是哪个库扛不住strings /opt/opencv455/lib/libopencv_videoio.so.4.5.5 | grep GLIBCXX_看它要求的最低版本。然后走两条路一是用发行版自带的包管理器升级 GCC 及相关运行库特别是libstdc.so.6二是直接换一个构建环境更接近你机器的预编译包。你自己写代码无法绕过这个限制因为它是运行时加载器决定的。5.4 一运行就段错误多个 OpenCV 版本的动态库被同时加载程序能编译也能启动但一调用cv::imread或者函数返回时 Mat 析构段错误就来了gdb 里看调用栈还特别难看懂。这类问题的源头几乎都是系统里有多个 OpenCV 版本在打架。程序主链接用了/opt/opencv455/lib下的库但某个间接依赖把你的LD_LIBRARY_PATH之外的另一个版本带了进来或者同名 soname 的库在不同目录下各存在一份动态链接器按搜索顺序加载了先找到的那个于是头文件的声明、内存布局和实际的库实现不是同一套。分配内存的模块和释放内存的模块属于不同构建析构时崩掉是很自然的结果。排查手段就一条ldd ./your_app | grep opencv看输出列表里是不是混了多个目录的库。看到几条不同前缀的路径就挨个检查环境变量里是否残留了旧的 OpenCV 路径把不用的目录从LD_LIBRARY_PATH里清掉。根治办法是编译时用-Wl,-rpath,/opt/opencv455/lib把库路径写死让运行期优先锁定唯一来源不给环境变量串位的机会。5.5 PNG 读不出来、视频打不开、窗口黑屏第三方依赖库没对上还有一种更隐蔽的“半瘫痪”状态opencv_version正常探针也输出encode_png1或为 0但读 JPG 返回空 MatVideoCapture打开 MP4 没反应highgui 弹窗直接报错关闭。原因在预编译包的依赖链上。OpenCV 的图像编解码、视频解封装、GUI 显示靠的是它链接的 libpng、libjpeg、FFmpeg、GTK 这些系统运行库。打包者在构建时用的依赖版本和运行库跟你的系统大概率不完全一致。如果库文件里记录了对libpng16.so.16的要求而系统只有libpng12编译不报错运行期功能就丢。解决顺序是先用ldd检查libopencv_imgcodecs.so.4.5.5、libopencv_videoio.so.4.5.5、libopencv_highgui.so.4.5.5的依赖清单确认哪些系统库缺失或版本不匹配。然后通过发行版的包管理器补齐对应运行库。如果 GUI 模块的 GTK 依赖实在对不上而你又不真的需要弹窗就把 highgui 从这个项目里摘出去用-lopencv_core -lopencv_imgproc -lopencv_imgcodecs编译功能反而更干净。视频解码补 FFmpeg 相关运行库后通常能恢复但要注意预编译包链接的 FFmpeg 版本比系统新时同样要换包或升级运行库。6. 把“解压即用”变成“一键切版本”环境脚本加三个验证动作预编译包用顺手之后最大的痛点是环境变量管理。与其在.bashrc里堆一堆不可追溯的 export不如把环境集中在脚本里。下面这个脚本是给/opt/opencv455专门用的其他版本照此复制一份即可# env-opencv455.sh export OPENCV455_HOME/opt/opencv455 export LD_LIBRARY_PATH$OPENCV455_HOME/lib:$LD_LIBRARY_PATH export PKG_CONFIG_PATH$OPENCV455_HOME/lib/pkgconfig:$PKG_CONFIG_PATH每次在终端里source env-opencv455.sh当前会话就切到 4.5.5。编译时让 CMake 取这个环境变量决定OpenCV_DIRcmake -S . -B build -DOpenCV_DIR$OPENCV455_HOME/lib/cmake/opencv4 cmake --build build切换版本时source env-opencv49.sh就能换个目录而不是去改全局变量。换完执行三个验证动作opencv_version输出对应版本号ldd ./build/demo | grep opencv确认所有库来源一致跑一次探针程序确认图像编码链路正常。三步全过再进入业务开发。我之前在一台机器上并列放了三个版本的包最后被.bashrc里一长串 export 绕晕过程序跑起来加载的库路径跟头文件根本对不上排查了半个晚上才意识到是环境变量串位。从那次以后多版本管理一律走环境脚本不再往全局配置里追加。预编译包本身是省时间的别让环境管理把那点时间吃回去。希望帮到你。本文还有配套的精品资源点击获取