【图文详解】Ubuntu / Linux +VSCode 配置 CMake 编译 OpenCV 超详细教程

Ne0inhk

14 Mar 2026 — 18 min read

💪图像算法工程师 | 深耕并挚爱的图像处理💪
💪🧑‍💻🔍✨📈 持续为你点亮技术灯塔，专栏最新动态如下👇：
📝《图像去噪》
📝《超分辨率重建》
📝《语义分割》
📝《风格迁移》
📝《目标检测》
📝《图像增强》
📝《模型优化》
📝《模型实战部署》
📝《图像配准融合》
📝《数据集》
📝《高效助手》
📝《C++》
📝《Qt》
📝《ISP算法》
📝《Linux》
📝B站

在 Linux 环境下进行计算机视觉开发，OpenCV 是必备的开源库，而 VSCode 凭借轻量、高效的特性成为主流编辑器。本文将手把手教你在 Ubuntu 系统中通过 CMake 编译安装 OpenCV，并完成 VSCode 的全流程配置，解决编译、链接、运行中的常见问题，让你快速搭建可直接开发的 OpenCV 环境。

一、OpenCV 核心编译流程
二、下载 OpenCV 源码包
三、安装编译依赖与工具
四、CMake 配置与 OpenCV 编译
五、配置 OpenCV 系统环境变量
六、验证 OpenCV 安装成功
- 6.1 安装mlocate工具
- 6.2 验证OpenCV
七、VSCode 中配置 OpenCV 开发环境
八、OpenCV 测试代码与运行
- 8.1 测试代码
- 8.2 运行代码
九、总结

一、OpenCV 核心编译流程

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

二、下载 OpenCV 源码包

打开 OpenCV 官方下载地址：OpenCV，选择所需版本（本文以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，执行下面指令：

# 安装CMake sudo apt install cmake # 安装make sudo apt install make

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

cmake --version make --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.0 mkdir build cd 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 -D OPENCV_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/pkgconfig export 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 <opencv2/…>标红报错。

按下快捷键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":"2.0.0",// OpenCV 专用构建任务"tasks":[{"label":"g++ build opencv",// 任务唯一 ID，被 launch.json 中的 preLaunchTask 引用。按 F5 → VSCode 先执行这个任务 → 再启动调试"type":"shell",// shell 命令任务，可以执行 bash，可以使用 $(...)，可以使用管道、变量替换等"command":"/usr/bin/bash",// 启动 bash 解释器执行命令"args":[// bash -c "xxx" 让 bash 执行后面的整条字符串命令"-c","g++ -g ${file} -o ${fileDirname}/${fileBasenameNoExtension} -std=gnu++14 $(pkg-config --cflags --libs opencv4)"],"options":{"cwd":"${fileDirname}"// 等价于：cd 当前cpp文件所在目录},"problemMatcher":["$gcc"// 让 VSCode 解析 g++ 的报错信息，并自动跳转到错误行],"group":{"kind":"build",// 构建类任务"isDefault":false// 不是默认构建任务}},// VSCode 自动生成的“普通 C++ 编译任务”{// VSCode C++ 插件自动帮你生成的通用 C++ 编译模板"type":"cppbuild","label":"C/C++: g++ 生成活动文件","command":"/usr/bin/g++","args":["-fdiagnostics-color=always","-g","${file}","-o","${fileDirname}/${fileBasenameNoExtension}"],"options":{"cwd":"${fileDirname}"},"problemMatcher":["$gcc"],"group":{"kind":"build","isDefault":false// 按 Ctrl+Shift+B，默认执行的就是这个任务},"detail":"调试器生成的任务。"}]}

八、OpenCV 测试代码与运行

8.1 测试代码

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

#include<opencv2/opencv.hpp>#include<iostream>usingnamespace cv;usingnamespace 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();return0;}

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 <opencv2/opencv.hpp>
| ^~~~~~~~~~~~~~~~~~~~
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，编译器自然找不到 <opencv2/opencv.hpp>

点的是右上角 ▶ 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配置提供基础支持。

🌟 感谢一路看到这里！

若本文对您有所启发，请毫不吝啬地留下 👍 点赞、⭐ 收藏、✍️ 评论三连——你的每一次互动，都是我持续输出干货的最大动力！

更多精彩内容已就绪：扫码关注下面「视觉研坊」 📸，让实战教程、独家案例与前沿资讯第一时间与你相遇！

目录