在 Ubuntu 上手动安装 OpenCV，常见问题不是“命令不会写”，而是源码目录怎么摆、`cmake` 之后为什么找不到库、测试程序为什么能编译却弹不出窗口。下面按“准备源码、安装依赖、编译安装、环境配置、样例验证”的顺序重新梳理一遍，方便你直接照着执行，也能在出错时快速判断问题卡在哪一步。
准备安装包与源码目录
本文使用的版本是 opencv-4.5.5.zip 和 opencv_contrib-4.5.5.zip。两份源码都下载完成后，先分别解压，再将解压后的 opencv_contrib 文件夹放入解压后的 opencv 文件夹内。
这一步的重点是先把源码结构整理好，后续进入 opencv 目录执行编译命令时，目录关系保持一致，排查问题会更直接。
先装好编译依赖
开始编译前，先安装构建工具、图形界面相关库，以及常见的图像编解码依赖。原始命令如下：
sudo apt-get install build-essential
sudo apt-get install cmake git libgtk2.0-dev pkg-config libavcodec-dev libavformat-dev libswscale-dev
sudo apt-get install python-dev python-numpy libtbb2 libtbb-dev libjpeg-dev libpng-dev libtiff-dev libjasper-dev libdc1394-22-dev
如果你后面需要运行带窗口显示的测试程序，像 libgtk2.0-dev 这类依赖就比较关键；如果缺少图像编解码相关库，往往会体现在编译功能裁剪或运行时报错上。
在 Ubuntu 上编译并安装 OpenCV 4.5.5
1. 创建 build 目录
进入 opencv 源码目录后，新建一个单独的 build 目录：
cd opencv
mkdir build
把编译过程放在独立目录里，后续清理缓存、重新生成工程都会更方便。
2. 运行 CMake 生成编译配置
切换到 build 目录，执行下面的命令：
cd build
sudo cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/usr/local -D OPENCV_GENERATE_PKGCONFIG=ON ..
这里保留了几个关键参数：
CMAKE_BUILD_TYPE=Release：使用发布模式编译；CMAKE_INSTALL_PREFIX=/usr/local：安装到/usr/local；OPENCV_GENERATE_PKGCONFIG=ON：生成pkg-config所需信息，便于后面查询版本和链接库。
3. 编译并安装
CMake 通过后，继续执行编译与安装：
sudo make -j4
sudo make install
-j4 表示使用 4 个并行任务编译，适合多数常见环境；如果机器核心数不同，也可以按实际情况调整。
补齐库路径与 pkg-config 环境
OpenCV 安装完成后，如果系统还找不到对应动态库，通常需要补充库路径并刷新缓存。
添加动态库搜索路径
先打开配置文件：
sudo gedit /etc/ld.so.conf
在文件中加入：
/usr/local/lib
保存退出后执行：
sudo ldconfig
这一步的作用是让系统重新加载动态链接库缓存。
配置 PKG_CONFIG_PATH
如果你希望用 pkg-config 查询 OpenCV 版本或在编译时读取库信息，还需要补上环境变量。
先打开：
sudo gedit /etc/bash.bashrc
在文件末尾添加两行：
PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib/pkgconfig
export PKG_CONFIG_PATH
保存后执行：
source /etc/bash.bashrc
然后用下面的命令检查版本：
pkg-config opencv --modversion
如果这里能够正常返回版本号，说明 pkg-config 这一层已经打通。
用一个最小 C++ 程序验证安装结果
安装完成后，最直接的验证方式就是编译并运行一个简单示例，确认头文件、链接库和图像窗口都能正常工作。
Makefile 示例
CXX ?= g++
main:
g++ main.cpp -o main -lopencv_stitching -lopencv_objdetect \
-lopencv_photo -lopencv_calib3d -lopencv_features2d -lopencv_flann -lopencv_highgui \
-lopencv_ml -lopencv_imgcodecs \
-lopencv_video -lopencv_imgproc -lopencv_core -ldl -lm -lpthread -lrt
clean:
rm -rf main
main.cpp 示例
#include <cstdio>
#include <iostream>
#include "opencv2/opencv.hpp"
using namespace std;
using namespace cv;
int main(int argc, char** argv) {
Mat img = imread("./car.jpg", IMREAD_GRAYSCALE);
if (img.empty()) {
cout << "read image error" << endl;
return -1;
}
imshow("car", img);
waitKey(0);
return 0;
}
编译与运行
make
./main
如果程序能正常读取 ./car.jpg 并弹出灰度图窗口，说明当前这套安装至少已经覆盖了基础读图、显示和链接流程。若控制台输出 read image error，优先检查图片路径；若编译阶段报缺少库，再回头核对前面的安装与环境变量配置。
VS Code Remote + XQuartz 的 X11 转发设置
如果你是在远程 Ubuntu 环境里，通过 VS Code Remote 连接并希望把 OpenCV 的图形窗口转发到本地，还需要确认 SSH 配置里开启了 X11 转发。原始配置如下：
ForwardX11 yes
ForwardX11Trusted yes
ForwardAgent yes
这部分通常用于远程显示 imshow 窗口。若程序本身能运行，但窗口始终不出现，就要把排查重点放在 X11 转发链路，而不只是 OpenCV 安装本身。
