一、OpenCV 核心编译流程

Linux 下编译安装 OpenCV 遵循源码解析 - 配置 - 编译 - 安装的标准流程，核心依托 CMake 生成适配系统的编译脚本，再通过 make 完成编译，整体流程下，本博文将会围绕此流程逐步讲解配置方法：

二、下载 OpenCV 源码包

打开 OpenCV 官方下载地址：https://opencv.org/releases/，选择所需版本（本文以4.10.0为例），下载Sources源码包：

将下载的opencv-4.10.0.zip放到 Ubuntu 的指定目录（本文示例：~/app/OpenCv4.10.0/）

三、安装编译依赖与工具

在进行 OpenCV 编译前，需要先安装 CMake、make 编译工具，以及 OpenCV 所需的基础依赖库，所有操作均在终端中执行。

3.1 解压源码包

进入源码包存放目录，右键打开终端：

执行解压命令：

unzip opencv-4.10.0.zip

解压完成后会生成opencv-4.10.0源码目录。

3.2 安装 CMake 和 make

安装CMake和 make，执行下面指令：

# 安装CMakesudo apt install cmake#安装makesudo apt install make

验证安装：输入以下命令，显示版本号即安装成功：

cmake --versionmake --version

3.3 安装 OpenCV 核心依赖包

执行以下命令安装编译所需的依赖库（涵盖图形界面、图像编解码、视频处理等功能）：

sudo apt-get install build-essential libgtk2.0-dev libgtk-3-dev libavcodec-dev libavformat-dev libjpeg-dev libswscale-dev libtiff5-dev libopenexr-dev libtbb-dev

等待依赖包下载安装完成，过程中若出现确认提示，输入y回车即可。

四、CMake 配置与 OpenCV 编译

采用源码目录与编译目录分离的规范，在源码目录内新建build文件夹，所有编译文件均存放在该文件夹中，避免污染源码。

4.1 创建 build 编译目录

进入解压后的opencv-4.10.0目录，右键新建文件夹并命名为build，或通过终端执行：

cd opencv-4.10.0mkdir buildcd build

4.2 CMake 生成 Makefile

根据开发需求选择发布模式（Release） 或调试模式（Debug），在 build 目录下执行对应的 CMake 命令，核心是生成适配系统的 Makefile。

4.2.1 模式 1：发布模式（边缘部署 / 实际开发使用）

如果需要用于边缘部署，轻量OpenCV，体积小、运行快，开启编译器最高级优化，无调试信息，执行下面指令：

cmake -D CMAKE_BUILD_TYPE=Release -D OPENCV_GENERATE_PKGCONFIG=YES ..

4.2.2 模式 2：调试模式（仅调试 OpenCV 源码时使用）

如果需要调试OpenCV源码本身，生成的库包含调试信息，可通过 gdb 调试 OpenCV 源码，但运行速度慢、库体积大，执行下面指令：

cmake -D CMAKE_BUILD_TYPE=Debug -DOPENCV_GENERATE_PKGCONFIG=YES ..

指令参数解析：

cmake：基础指令，启动 CMake 工具，用于解析上级目录的 OpenCV 源码配置文件（CMakeLists.txt），生成适配 Linux 系统的编译脚本（Makefile）。-D：CMake 参数定义前缀，用于设置编译变量CMAKE_BUILD_TYPE=Release/Debug：指定编译模式OPENCV_GENERATE_PKGCONFIG=YES：强制生成 opencv4.pc 配置文件，解决 OpenCV4.x 默认不生成该文件的问题，方便后续通过 pkg-config 获取编译链接参数..：指定 CMake 解析的 CMakeLists.txt 位于当前目录的上级目录（源码根目录）

执行结果：终端会输出系统环境检测、依赖检测信息，最终显示Configuring done、Generating done即配置成功，build 目录下会生成 Makefile 及各类编译配置文件，如下：

4.3 make 编译源码

在 build 目录下执行make命令，调用 g++ 编译所有 OpenCV 源码文件，该过程耗时较长（根据电脑配置，约 10-30 分钟）：

make

编译成功标志：终端最终显示100%，且无报错信息，所有目标文件编译完成。

4.4 make install 安装 OpenCV

将编译好的库文件（.so）、头文件、可执行文件安装到 Ubuntu 系统默认路径（/usr/local/），执行命令：

sudo make install

安装完成后，OpenCV 的头文件存放在/usr/local/include/opencv4/，库文件存放在/usr/local/lib/。

五、配置 OpenCV 系统环境变量

安装完成后，需要配置系统环境变量，让 Ubuntu 能识别 OpenCV 的库文件和 pkg-config 配置文件，否则运行程序时会出现库文件找不到的错误。

5.1 添加 OpenCV 库路径

新建并编辑 opencv4.conf 配置文件，指定库文件路径：

sudo gedit /etc/ld.so.conf.d/opencv4.conf

指令解析：以管理员权限打开opencv4.conf配置文件（文件不存在则新建，空白则直接编辑）。

指定 OpenCV 编译后生成的库文件（.so文件）所在的目录，将下面内容写到打开的空白编辑界面中（OpenCV 默认库文件路径），保存并关闭文件：

/usr/local/lib

执行刷新系统共享库缓存命令，让路径生效：

sudo ldconfig

5.2 配置 pkg-config 路径

通过配置 bash 文件，让系统识别 OpenCV 的.pc 配置文件，方便编译时通过 pkg-config 自动获取头文件和库文件路径。

5.2.1 编辑系统级 bash 配置文件

以管理员权限打开系统级的 bash 配置文件，这个文件是 Linux 终端的 “全局设置文件”，修改后所有用户的终端都会生效。执行下面指令：

sudo gedit /etc/bash.bashrc

5.2.2 添加环境变量

在打开的巴适文件末尾添加以下两行内容：

PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib/pkgconfigexport PKG_CONFIG_PATH

添加内容解析：

PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib/pkgconfig：告诉pkg-config工具（编译辅助工具）去哪里找 OpenCV 的配置文件（.pc文件）。相当于给编译器的 “导航仪” 更新地图，让它知道 OpenCV 的头文件、库文件位置，以及编译时需要链接哪些依赖。export PKG_CONFIG_PATH：把上面的路径设置为系统环境变量，让所有终端会话都能识别

5.2.3 刷新 bash 配置，立即生效

立即生效 bash 配置，无需重启终端，执行下面指令：

source /etc/bash.bashrc

5.2.4 可选：配置用户级 bash 文件（双重保障）

终端输入指令：

gedit ~/.bashrc

在最后一行输入：

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH

刷新，让配置生效

source ~/.bashrc

5.3 验证环境变量配置

执行以下命令，查看 PKG_CONFIG_PATH 值，包含/usr/local/lib/pkgconfig即配置成功：

echo $PKG_CONFIG_PATH

六、验证 OpenCV 安装成功

6.1 安装mlocate工具

安装mlocate工具（包含locate命令）,这是 Linux 的 “文件快速搜索工具”，能快速查找系统里的文件（比如验证 OpenCV 的配置文件是否存在。执行下面指令安装：

sudo apt-get install mlocate

检验是否安装成功：

mlocate --version

搜索OpenCV配置文件:

locate opencv4.pc

输出/usr/local/lib/pkgconfig/opencv4.pc即表示配置文件存在。

6.2 验证OpenCV

通过pkg-config工具查询 OpenCV4 的版本号，如果能输出具体版本号（如4.10.0），说明 OpenCV 的路径、配置都已生效，编译环境配置成功；如果报错，说明配置步骤有问题。执行下面指令：

pkg-config --modversion opencv4

七、VSCode 中配置 OpenCV 开发环境

完成系统级的 OpenCV 安装后，需要配置 VSCode，让其识别 OpenCV 头文件、实现编译和调试，核心是配置 3 个关键文件：c_cpp_properties.json、launch.json、tasks.json，并解决 Code Runner 插件的运行问题。

c_cpp_properties.json→只管智能提示tasks.json→只管编译launch.json→只管运行 + 调试

7.1 新建 VSCode 项目

打开 VSCode，新建文件夹作为项目目录（示例：test_opencv）

在项目目录中新建.cpp文件（示例：opencv_demo.cpp）

7.2 配置 c_cpp_properties.json（识别头文件）

该文件用于让 VSCode 的 IntelliSense 识别 OpenCV 头文件，避免代码中#include标红报错。

按下快捷键Ctrl+Shift+P，输入edit或编辑配置，选择C/C++: 编辑配置 (JSON)。

自动生成.vscode/c_cpp_properties.json文件，替换为以下内容：

关键配置：/usr/local/include/opencv4为 OpenCV 头文件路径，添加后 VSCode 可正常索引 OpenCV 头文件。，c_cpp_properties.json文件内容为：

{    "configurations": [        {            "name": "Linux",            "includePath": [                "${workspaceFolder}/**",                "/usr/local/include/opencv4",        // 添加头文件路径                "/usr/include/**"            ],            "defines": [],            // "compilerPath": "/usr/bin/gcc",               // gcc 路径            "compilerPath": "/usr/bin/g++",               // g++ 路径            "cStandard": "c17",            "cppStandard": "gnu++14",            "intelliSenseMode": "linux-gcc-x64"        }    ],    "version": 4}

7.3 配置 launch.json（调试配置）

该文件用于 VSCode 的 gdb 调试，指定调试的可执行文件、调试器路径等，依赖 tasks.json 的编译任务。

按下Ctrl+Shift+D，打开运行和调试，点击创建一个launch.json文件，自动生成文件后替换为以下内容：

关键配置：preLaunchTask: "g++ build opencv"指定调试前先执行的编译任务，需与 tasks.json 中的任务标签一致。launch.json文件内容如下：

{    "version": "0.2.0",    "configurations": [        {            "name": "g++ debug opencv",   // 调试配置名称            "type": "cppdbg",           // Linux下适配gdb的调试类型            "request": "launch",            // 调试的可执行文件路径，和tasks.json的输出路径一致            "program": "${fileDirname}/${fileBasenameNoExtension}",            "args": [],                   // 程序运行参数（无则留空）            "stopAtEntry": false,         // 不自动暂停在main函数入口            "cwd": "${fileDirname}",            "environment": [],            "externalConsole": false,     // 避免OpenCV图片窗口闪退            "MIMode": "gdb",            "setupCommands": [                {                    "description": "为gdb启用整齐打印",                    "text": "-enable-pretty-printing",                    "ignoreFailures": true                }            ],            // 调试前先执行编译任务，label必须和tasks.json中的label一致            "preLaunchTask": "g++ build opencv",             // 与tasks.json文件中label一致            "miDebuggerPath": "/usr/bin/gdb"  // Linux默认gdb路径        }    ]}

7.4 配置 tasks.json（编译任务）

该文件定义 VSCode 的编译命令，核心是将 OpenCV 的编译链接参数融入 g++ 命令，实现一键编译。

在.vscode文件夹中手动新建tasks.json文件或者通过Debug C/C++File创建：

写入以下内容，包含OpenCV 专用编译任务和普通 C++ 编译任务：

核心命令：$(pkg-config --cflags --libs opencv4)会自动获取 OpenCV 的头文件路径（-I）和库文件链接参数（-L/-l），无需手动写死路径。tasks.json文件内容为：

{    "version": "0.2.0",    "configurations": [        {            "name": "g++ debug opencv",   // 调试配置名称            "type": "cppdbg",           // Linux下适配gdb的调试类型            "request": "launch",            // 调试的可执行文件路径，和tasks.json的输出路径一致            "program": "${fileDirname}/${fileBasenameNoExtension}",            "args": [],                   // 程序运行参数（无则留空）            "stopAtEntry": false,         // 不自动暂停在main函数入口            "cwd": "${fileDirname}",            "environment": [],            "externalConsole": false,     // 避免OpenCV图片窗口闪退            "MIMode": "gdb",            "setupCommands": [                {                    "description": "为gdb启用整齐打印",                    "text": "-enable-pretty-printing",                    "ignoreFailures": true                }            ],            // 调试前先执行编译任务，label必须和tasks.json中的label一致            "preLaunchTask": "g++ build opencv",             // 与tasks.json文件中label一致            "miDebuggerPath": "/usr/bin/gdb"  // Linux默认gdb路径        }    ]}

八、OpenCV 测试代码与运行

8.1 测试代码

在opencv_demo.cpp中写入以下代码，实现图片读取与显示，注意替换图片绝对路径为自己的图片路径：

#include<opencv2/opencv.hpp>#include<iostream>using namespace cv;using namespace std;intmain(){    // 读取图片，替换为自己的图片绝对路径    Mat img = imread("/home/yizuou/code/C++/test_opencv/image/OIP-C.jpg");    if (img.empty()) {        cout << "图片读取失败！" << endl;        return -1;    }    // 显示图片    imshow("Test Image", img);    waitKey(0);  // 等待按键关闭窗口    destroyAllWindows();    return 0;}

8.2 运行代码

8.2.1 Ctrl+Shift+B编译后运行

按下Ctrl+Shift+B，选择g++ build opencv，VSCode 会执行编译命令，编译成功后在终端中执行生成的可执行文件：

./opencv_demo

运行成功：弹出图片显示窗口，显示指定的图片，按下任意键关闭窗口。

8.2.2 F5运行

比较省事的运行是直接按下键盘上的F5键，VSCode会执行：

launch.json → preLaunchTask → tasks.json → g++ 编译 → 生成可执行 → gdb 启动 → 运行程序

这是完整工业级调试运行流程，可以直接运行后出图：

8.2.3 ▶ Run Code

8.2.3.1 可能报错

通过run code运行代码时报错：

报错如下：

cd "/home/yizuou/code/C++/test_opencv/" && g++ opencv_demo.cpp -o opencv_demo && "/home/yizuou/code/C++/test_opencv/"opencv_demo

opencv_demo.cpp:1:10: fatal error: opencv2/opencv.hpp: 没有那个文件或目录

1| #include

|^~~~~~~~~~~~~~~~~~~~

compilation terminated.

8.2.3.2 报错分析

从日志可以看到：cd "/home/yizuou/code/C++/test_opencv/" && g++ opencv_demo.cpp -o opencv_demo，根本没有：$(pkg-config --cflags --libs opencv4)。没有 -I/usr/local/include/opencv4，编译器自然找不到

点的是 右上角 ▶ Run Code，用 VSCode 的 Code Runner 插件在跑，此插件 的运行方式：

g++ xxx.cpp -o xxx

Code Runner 插件不会读取 tasks.json，不会读取 launch.json，不会读取 c_cpp_properties.json，它只会用自己的默认模板命令。

8.2.3.3 解决办法

修改 VSCode 的 Code Runner 插件的 cpp 执行模板，让它自动加上：$(pkg-config --cflags --libs opencv4)

点 ▶ Run Code，执行的就不再是：g++ test.cpp -o test，而是：g++ test.cpp -o test $(pkg-config --cflags --libs opencv4)

按下Ctrl + Shift + P，搜索：Preferences: Open Settings (JSON)，输入下面内容：

"code-runner.executorMap": {"cpp":"cd $dir && g++ $fileName -o $fileNameWithoutExt$(pkg-config --cflags --libs opencv4) && ./$fileNameWithoutExt"}

重启 VSCode。

8.2.3.4 run code运行测试

点击 ▶ 之后，真正执行的过程见下，自动编译，自动链接 OpenCV，自动运行。

cd 当前目录 && g++ opencv_demo.cpp -o opencv_demo $(pkg-config --cflags --libs opencv4) && ./opencv_demo

九、总结

本文详细介绍了在Ubuntu系统中通过CMake编译安装OpenCV的全流程。主要内容包括：下载OpenCV源码、安装编译工具与依赖库、使用CMake配置生成Makefile、执行make编译源码等关键步骤。文章提供了发布模式和调试模式两种配置方案，并解析了各命令参数作用，帮助开发者快速搭建OpenCV开发环境。通过图文结合的方式，详细展示了每个操作环节的终端输出，便于读者对照验证。最终编译生成的OpenCV库可应用于计算机视觉项目开发，为后续VSCode配置提供基础支持。