opencv在linux需手动编译安装，关键步骤包括：装全依赖（如libjpeg-dev、libavcodec-dev、libgtk-3-dev等）、禁用ippicv自动下载并手动配置路径、opencv_contrib版本严格匹配主库并指定绝对路径、安装后验证pkg-config和python软链。
OpenCV 在 Linux 上不是“一键装好就能用”的库，编译安装过程里最容易卡在依赖缺失、ippicv 下载失败、opencv_contrib 路径错位、或 pkg-config 找不到路径这几个环节。直接用 apt install python3-opencv 虽快，但版本老旧（Ubuntu 22.04 默认是 4.5.x，而当前稳定版已是 4.9.0），且缺 dnn 模块支持 ONNX、缺 aruco、缺 sift 等关键算法——这些在实际项目里基本绕不开。
依赖必须一次装全，漏一个就 runtime 报错
很多教程只列基础依赖，结果编译成功、运行时一调 cv2.imread() 就返回 None，或 cv2.dnn.readNet() 报 “Unsupported layer type”——根本原因是图像/视频/深度学习相关解码器没装全。
-
libjpeg-dev libpng-dev libtiff-dev libwebp-dev：缺任意一个，imread对应格式读不出 -
libavcodec-dev libavformat-dev libswscale-dev libv4l-dev：缺就无法打开 USB 摄像头或 MP4 文件（cv2.VideoCapture(0)返回空对象） -
libgtk-3-dev（不是libgtk2.0-dev）：Ubuntu 22.04+ 必须用 GTK3，否则cv2.imshow()直接段错误 -
python3-dev python3-numpy：Python 绑定编译失败的头号原因 -
libatlas-base-dev gfortran：加速矩阵运算，不装也行，但cv2.gemm()类函数会慢 3–5 倍
推荐一次性执行：
sudo apt update && sudo apt install -y \ build-essential cmake git pkg-config \ libgtk-3-dev \ libavcodec-dev libavformat-dev libswscale-dev libv4l-dev \ libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \ libjpeg-dev libpng-dev libtiff-dev libwebp-dev \ libdc1394-22-dev libxvidcore-dev libx264-dev \ libtbb2 libtbb-dev libeigen3-dev \ python3-dev python3-numpy \ libatlas-base-dev gfortran
cmake 配置必须关掉自动下载，手动填 ippicv 路径
默认 cmake 会尝试从 GitHub 下载 ippicv（Intel IPP 加速库），但国内几乎 100% 失败，卡在 Downloading ippicv_*.tgz 不动，且无超时提示。等半小时后中断，再 make 会报 fatal error: ippcp.h: No such file or directory。
正确做法是提前下载并硬编码路径：
Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。
- 去 opencv_3rdparty/releases 找对应 OpenCV 版本的
ippicv包（如 4.9.0 对应ippicv_2020_lnx_20191018.tgz） - 解压后把
ippicv/目录放到opencv-4.9.0/3rdparty/ippicv/下（注意路径层级） -
cmake时加参数：-D OPENCV_DNN_CUDA=ON -D OPENCV_ENABLE_NONFREE=ON -D BUILD_opencv_dnn=ON -D OPENCV_DNN_VENDORED=OFF（若需 CUDA 加速） - 最关键一句：
-D OPENCV_DOWNLOAD_IPPICV=OFF，彻底禁用自动下载
opencv_contrib 必须显式指定路径，且版本严格匹配
人脸识别（cv2.face）、SIFT/SURF（cv2.SIFT_create()）、文本检测（cv2.text）等都在 opencv_contrib 里。但它的 commit hash 必须和主库完全一致，否则 cmake 报 module 'xxx' not found 或编译中途失败。
- 比如你下的是
opencv-4.9.0.zip，就得去 opencv_contrib/releases/tag/4.9.0 下同 tag 的 zip - 解压后路径结构必须是：
~/opencv_contrib-4.9.0/modules/ -
cmake时写绝对路径：-D OPENCV_EXTRA_MODULES_PATH=/home/yourname/opencv_contrib-4.9.0/modules - 别用相对路径，也别漏掉末尾的
/modules
安装后必须验证 pkg-config 和 Python import 双通路
装完不代表能用。很多人 make install 成功，但 pkg-config --modversion opencv4 报错，或 import cv2 提示 ModuleNotFoundError——这是因为 cv2.so 没放对位置，或系统找不到头文件。
- 检查是否注册了 pkg-config：
ls /usr/local/lib64/pkgconfig/opencv4.pc（存在才说明 C/C++ 可用） - 补环境变量（仅影响当前 shell）：
export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig:$PKG_CONFIG_PATH - Python 绑定默认装在
/usr/local/python/cv2/python-3.x/cv2.cpython-*.so，需软链到 site-packages：sudo ln -s /usr/local/python/cv2/python-3.10/cv2.cpython-310-x86_64-linux-gnu.so /usr/local/lib/python3.10/site-packages/cv2.so - 验证：
python3 -c "import cv2; print(cv2.__version__)"输出4.9.0，且cv2.SIFT_create()不报错才算真正可用
最常被忽略的是 Python 软链这一步——它不自动做，也不报错，但 import 就失败。别跳过。
