在 Linux 环境下进行计算机视觉开发，OpenCV 是必备的开源库，而 VSCode 凭借轻量、高效的特性成为主流编辑器。本文将手把手教你在 Ubuntu 系统中通过 CMake 编译安装 OpenCV，并完成 VSCode 的全流程配置，解决编译、链接、运行中的常见问题，让你快速搭建可直接开发的 OpenCV 环境。一、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 解压源码包
进入源码包存放目录，右键打开终端：
执行解压命令：
解压完成后会生成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 分钟）：
编译成功标志：终端最终显示100%，且无报错信息，所有目标文件编译完成。
4.4 make install 安装 OpenCV
将编译好的库文件（.so）、头文件、可执行文件安装到 Ubuntu 系统默认路径（/usr/local/），执行命令：
安装完成后，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 默认库文件路径），保存并关闭文件：
执行刷新系统共享库缓存命令，让路径生效：
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 配置，无需重启终端，执行下面指令：
5.2.4 可选：配置用户级 bash 文件（双重保障）
终端输入指令：
在最后一行输入：
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
刷新，让配置生效
5.3 验证环境变量配置
执行以下命令，查看 PKG_CONFIG_PATH 值，包含/usr/local/lib/pkgconfig即配置成功：
六、验证 OpenCV 安装成功
6.1 安装mlocate工具
安装mlocate工具（包含locate命令）,这是 Linux 的 “文件快速搜索工具”，能快速查找系统里的文件（比如验证 OpenCV 的配置文件是否存在。执行下面指令安装：
sudo apt-get install mlocate
检验是否安装成功：
搜索OpenCV配置文件:
输出/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 会执行编译命令，编译成功后在终端中执行生成的可执行文件：
运行成功：弹出图片显示窗口，显示指定的图片，按下任意键关闭窗口。
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 插件在跑，此插件 的运行方式：
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配置提供基础支持。
