小白也能看懂！OpenCV 从零开始安装配置全教程（包含Windows / Ubuntu / 树莓派）系统详细操作配置教程

摘要

本教程是面向“小白也能懂”的OpenCV安装与配置全攻略，涵盖Windows、Ubuntu和树莓派三大平台，真正实现“从零开始”快速上手。文章详细讲解了OpenCV下载安装教程、OpenCV安装、Ubuntu安装OpenCV、树莓派安装OpenCV等步骤，手把手指导小白用户进行环境准备、依赖库安装、解压与环境变量配置、CMake编译、源码编译与apt-get安装等操作。通过本教程，小白也能一步步完成OpenCV安装配置，为后续图像处理与计算机视觉项目开发打下坚实基础。

小白也能看懂！OpenCV 从零开始安装配置全教程（包含Windows / Ubuntu / 树莓派）系统详细操作配置教程

前言
准备工作与基础知识
1. 什么是 OpenCV？
2. 为什么要学习 OpenCV？
3. 运行环境与系统要求
Windows 下安装 OpenCV
1. 环境准备
2. 下载 OpenCV 安装包
3. 解压与配置环境变量
4. 配置 Visual Studio/MinGW 编译环境
5. 验证安装（Hello OpenCV）
Ubuntu 下安装 OpenCV
1. 环境准备
2. 从 apt-get 安装（推荐快速入门）
3. 从源码编译安装（适合高级定制）
4. 验证安装（Python 与 C++ 示例）
树莓派（Raspberry Pi）下安装 OpenCV
1. 准备树莓派硬件与系统
2. 使用 apt-get 直接安装
3. 从源码编译安装（性能优化）
4. 验证安装与摄像头测试
常见问题及故障排查
1. 环境变量不生效
2. CMake 找不到依赖
3. Python 导入失败
4. 编译报错“缺少 xxx 库”
总结与扩展阅读

前言

本教程专为从未接触过图像处理、编译配置的小白用户打造。我们将带你“从零开始”，逐步完成在不同系统（Windows、Ubuntu、树莓派）上安装和配置 OpenCV（Open Source Computer Vision Library）的全过程。只要你跟着步骤走，即使对命令行、编译环境、依赖库一无所知，也能轻松完成安装。

目标读者：零基础学习者、对图像处理感兴趣的同学、想动手搭建计算机视觉开发环境的初学者。
教程亮点：
1. 详细步骤图文结合（文字详尽说明）。
2. 包含常见报错及解决方案。
3. Windows、Ubuntu、树莓派三大平台全覆盖。
4. 关键词标注，让你快速检索 “opencv下载安装教程”、“opencv安装”、“ubuntu安装opencv”、“树莓派安装opencv” 等内容。

准备工作与基础知识

什么是 OpenCV？

OpenCV（Open Source Computer Vision Library）是一个开源的、跨平台的计算机视觉与机器学习软件库。它提供了上千个算法和函数，涵盖以下主要方向：

图像处理：图像读取、显示、保存、滤波、几何变换、阈值分割、形态学操作等。
特征检测与描述：如边缘检测（Canny）、角点检测（Harris、Shi-Tomasi）、ORB、SIFT、SURF 等。
目标识别与跟踪：人脸检测与识别（Haar 特征、DNN）、物体跟踪（KCF、MOSSE、CSRT 等）。
机器学习：支持 SVM、决策树、随机森林、神经网络等常见模型。
深度学习支持：可加载预训练的 Caffe、TensorFlow、Torch、Darknet 等模型进行推理。
三维重建与增强现实：立体匹配、相机标定等模块支持三维重建和 AR 应用。

OpenCV 社区非常活跃，文档齐全、示例丰富。对于计算机视觉入门和项目开发都是非常理想的选择。

为什么要学习 OpenCV？

功能强大且免费开源：几乎涵盖所有常见图像处理与计算机视觉需求。
跨平台支持：Windows、Linux（Ubuntu）、macOS、Android、iOS、树莓派等。
语言接口多样：C++（官方核心实现）、Python、Java、MATLAB 等接口，初学者可先用 Python 体验。
社区活跃，资料丰富：Stack Overflow、GitHub Issue、各种技术博客、官方文档、书籍等一应俱全。
工业与学术通用：无论是学术论文验证，还是工业项目快速落地，OpenCV 都是首选。

运行环境与系统要求

由于本教程覆盖 Windows、Ubuntu、树莓派 3 个系统，下面分别说明各自的最小要求，供小白用户简单确认。

平台	最低要求（推荐）
Windows	Windows 10（64 位），4 GB 内存以上，至少 10 GB 硬盘空间
Ubuntu	Ubuntu 18.04/20.04/22.04（64 位），4 GB 内存以上，至少 10 GB 硬盘
树莓派	Raspberry Pi 4（推荐 4GB or 8GB 内存），运行 Raspberry Pi OS（64 位），SD 卡 16GB 以上

网络连接：下载源码或依赖时需要联网，建议有稳定的网络。
开发环境：
- Windows：建议安装 Visual Studio Community（2019/2022）或配置 MinGW。
- Ubuntu：需要安装 gcc/g++、make、CMake 等常见开发工具。
- 树莓派：建议使用自带的终端环境，可直接 sudo apt-get 安装依赖。

后续部分会详细说明各自的前置准备和依赖安装。

Windows 下安装 OpenCV

在 Windows 系统上安装 OpenCV 最简单的方式就是下载官方提供的预编译安装包，然后配置系统环境变量和开发工具链（Visual Studio / MinGW）。本节将以 Visual Studio 2022 为例，手把手教你完成整个过程。

一、环境准备

操作系统：Windows 10 或更高，64 位（Win7/8 也可，但推荐 Win10 以上）。
Visual Studio Community 2022（免费版即可）
- 网站下载地址（仅供参考，具体版本以微软官网最新版本为准）：
  
  https://visualstudio.microsoft.com/zh-hans/vs/community/
- 在安装时，勾选“使用 C++ 的桌面开发”工作负载，确保安装：
  - MSVC v143 - VS 2022 C++ x64/x86 build tools
  - CMake 工具
  - Windows 10 SDK
Python（可选，若想用 Python 接口）
- Python 3.7 及以上版本均可，推荐 3.8/3.9。
- Windows 上安装时，必须勾选“Add Python to PATH”。
管理员权限：建议使用管理员身份运行安装程序与配置命令行，否则容易出现权限不足的问题。

二、下载 OpenCV 安装包

打开 OpenCV 官方 GitHub Release 页面：

https://github.com/opencv/opencv/releases
找到最新的稳定版本（如 4.8.0、4.7.0 等），对应 Windows 的预编译文件一般为 opencv-{version}-vc{msvc_version}.zip 或者 opencv-{version}-vc{msvc_version}-opencv_contrib.zip。
- 推荐下载：opencv-{version}-vc{msvc_version}.zip（此包已包含主模块，且自带 VS 预编译二进制）。
- 如果需要 contrib 模块（额外的算子、samples 等），可以下载 opencv_contrib 版本，但体积更大。
将下载好的压缩包放到一个容易找到的位置（如 D:\ 或 C:\Users\你的用户名\Downloads\）。

三、解压与配置环境变量

解压目录

右键点击下载的 opencv-*.zip，选择 “解压到 opencv-xxx\” （推荐路径：C:\opencv\）。

解压后，你会看到：

C:\opencv\├── build\│    ├── x64\│    │    ├── vc15\│    │    │    ├── bin\│    │    │    ├── lib\│    │    │    └── etc...│    └── ...├── samples\├── sources\└── ...

配置系统环境变量
- 右键 “此电脑” → “属性” → “高级系统设置” → “环境变量”。
- 在 “系统变量” 区域，找到 Path，选择后点击 “编辑”。
- 点击 “新建”，添加下面两项（根据你的解压路径修改）：
```
C:\opencv\build\x64\vc15\bin
C:\opencv\build\bin\Release
```
  说明：
  - vc15 表示 MSVC 15/.NET 2017 或更高版本，如果你的版本不一样，按实际目录填写。
  - 添加后，打开新的命令行（CMD / PowerShell），输入 opencv_version 无报错即生效。

四、配置 Visual Studio 编译环境

以下操作将演示如何在 Visual Studio 2022 中创建一个简单的 C++ 项目，并链接 OpenCV 库。

启动 Visual Studio 2022
- 点击 “创建新项目” → 选择 “空项目（Empty Project）” → 点击 “下一步”。
- 项目名称取为 HelloOpenCV，选择合适路径，如 D:\Projects\HelloOpenCV → 点击 “创建”。
配置附加包含目录
- 右击解决方案资源管理器中的项目 → “属性” → 左侧选择 “配置属性”→“C/C++”→“常规”→“附加包含目录”。
- 点击右侧的 “编辑”，添加：
```
C:\opencv\build\include
```
  说明：这样编译器才能找到 OpenCV 的头文件（.hpp、.h 等）。
配置附加库目录
- 同样在项目属性中，选择 “配置属性”→“链接器”→“常规”→“附加库目录”，添加：
```
C:\opencv\build\x64\vc15\lib
```
  该目录下包含 opencv_world480.lib（或 opencv_world470.lib，视版本而定）等库文件。
添加依赖库
- 项目属性 → “配置属性” → “链接器” → “输入” → “附加依赖项”，点击 “编辑”，将需要的 .lib 文件添加进去，例如：
```
opencv_world480.lib
```
  如果你下载的是 contrib 版本，可能需要添加其它模块的 lib，但 opencv_worldxxx.lib 已经包含所有模块，最简单。
设置运行时 DLL
- 由于编译时会链接动态库（.dll），运行 exe 前需要确保 C:\opencv\build\x64\vc15\bin 已加入系统 PATH（已在上一步完成）。
- 若未配置环境变量，可将 *.dll 文件复制到可执行文件所在目录。

五、验证安装（Hello OpenCV）

添加源文件
- 在项目中右键 “源文件” → “添加” → “新建项” → 选择 “C++ 文件”，命名为 main.cpp。

输入示例代码

#include <opencv2/opencv.hpp>
#include <iostream>int main() {// 创建一张 300x300 的黑色图像cv::Mat image = cv::Mat::zeros(300, 300, CV_8UC3);// 在图像中心画一个蓝色圆圈（BGR ）cv::circle(image, cv::Point(150, 150), 100, cv::Scalar(255, 0, 0), -1);// 显示窗口cv::imshow("Hello OpenCV", image);// 等待按键cv::waitKey(0);return 0;
}

编译与运行
- 按下 F5 或点击 “本地 Windows 调试器” 运行项目。
- 如果一切正常，将弹出一个名为 “Hello OpenCV” 的窗口，显示一个蓝色填充圆圈。
- 若窗口正常出现且无报错，则 Windows 平台上的 OpenCV 安装配置成功。

Ubuntu 下安装 OpenCV

在 Ubuntu 下安装 OpenCV 常见两种方式：通过 apt-get 直接安装（快速）、或者从源码编译安装（自由配置、性能更优）。本节将分别介绍二者，并为初学者标注重点。

一、环境准备

操作系统：Ubuntu 18.04/20.04/22.04 LTS（64 位）。
用户权限：需要能运行 sudo 命令。
网络环境：建议使用国内源（如阿里云、清华源）以加快下载速度。
- 修改 /etc/apt/sources.list，将官方源替换为国内镜像。（若不熟悉，可跳过，后续命令会慢一些）。
基本开发工具：在终端中执行：
```
sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y build-essential cmake git pkg-config
```
- build-essential：包含 gcc/g++、make 等常见工具。
- cmake：构建工具，用于从源码编译。
- git：克隆源码。
- pkg-config：管理安装库时查找包信息。

温馨提示：若已安装最新版 Ubuntu，build-essential、cmake 等工具一般自带，只需更新即可。

二、从 apt-get 安装（推荐快速入门）

安装 OpenCV 库及 Python 绑定
```
sudo apt-get install -y libopencv-dev python3-opencv
```
- libopencv-dev：OpenCV C++ 开发包，包含头文件和库。
- python3-opencv：Python3 接口，安装后可以直接在 Python 中 import cv2。

验证 C++ 接口

创建一个测试目录，例如 ~/opencv_test：
```
mkdir ~/opencv_test && cd ~/opencv_test
```

编写 main.cpp：

#include <opencv2/opencv.hpp>
#include <iostream>int main() {cv::Mat img = cv::Mat::zeros(200, 400, CV_8UC3);cv::putText(img, "Ubuntu OpenCV", cv::Point(50, 100),cv::FONT_HERSHEY_SIMPLEX, 1.0, cv::Scalar(0, 255, 0), 2);cv::imshow("Test", img);cv::waitKey(0);return 0;
}

使用 pkg-config 编译：
```
g++ main.cpp -o test `pkg-config --cflags --libs opencv4`
```
- 注意：Ubuntu 20.04 及以后的版本，OpenCV4 对应的 pkg-config 名称为 opencv4，若低版本，可能是 opencv。
运行：
```
./test
```
- 如果弹出标题为 “Test” 的窗口，且显示绿色文字 “Ubuntu OpenCV”，则说明安装成功。

验证 Python 接口

打开终端，输入 python3 进入交互式 Python：

python3
>>> import cv2
>>> print(cv2.__version__)
4.x.x
>>> img = cv2.imread("test.jpg")  # 若当前目录有图片文件
>>> cv2.imshow("img", img)
>>> cv2.waitKey(0)
>>> cv2.destroyAllWindows()

若能成功 import cv2，且能调用函数，就说明 Python 接口正常工作。

Tips：使用 sudo apt-get install libopencv-dev python3-opencv 安装的版本一般不是最新，若想体验最新版本或编译选项，请参阅下一节源码编译安装。

三、从源码编译安装（适合高级定制）

如果你想要：

OpenCV 最新稳定版/alpha 版；
自定义编译选项（是否启用 CUDA、是否启用 contrib 模块）；
优化性能（选择 TBB、OpenMP、多线程；或者使用 NEON、V4L2）。

就需要自行从源码编译。以下步骤示例基于 Ubuntu 20.04，OpenCV 4.8.0 为例。

1. 安装额外依赖

先安装编译 OpenCV 常用依赖库和拓展功能库，包括图像编解码、GUI 支持、视频 I/O、数学优化等：

sudo apt-get update
sudo apt-get install -y build-essential cmake git pkg-config \libjpeg-dev libpng-dev libtiff-dev libopenexr-dev libwebp-dev \libavcodec-dev libavformat-dev libswscale-dev libv4l-dev \libxvidcore-dev libx264-dev libgtk-3-dev libatlas-base-dev gfortran \python3-dev python3-numpy

说明关键依赖：

libjpeg-dev, libpng-dev, libtiff-dev 等：支持常见图像格式。
libavcodec-dev, libavformat-dev, libswscale-dev：FFmpeg 相关，用于视频读写。
libv4l-dev：Linux 视频采集接口，用于摄像头。
libgtk-3-dev：GUI 窗口显示支持。
libatlas-base-dev 或 libopenblas-dev：线性代数加速。
python3-dev, python3-numpy：Python 接口依赖。

2. 下载 OpenCV 与 OpenCV Contrib 源码

cd ~
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git

opencv/：主库源码。
opencv_contrib/：官方扩展模块（如 xfeatures2d、aruco、text 等）。

如果网络较慢，可考虑使用国内镜像，如 Gitee，或者先下载压缩包再解压。

3. 创建构建目录并使用 CMake 配置

cd ~/opencv
mkdir build && cd build

使用 cmake 命令生成 Makefile 或 Ninja 配置。以下示例配置较常用选项，适合大多数入门需求：

cmake -D CMAKE_BUILD_TYPE=Release \-D CMAKE_INSTALL_PREFIX=/usr/local \-D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \-D BUILD_EXAMPLES=ON \-D BUILD_TESTS=OFF \-D BUILD_DOCS=OFF \-D BUILD_PERF_TESTS=OFF \-D BUILD_opencv_python3=ON \-D ENABLE_NEON=ON \-D WITH_TBB=ON \-D WITH_V4L=ON \-D WITH_QT=OFF \-D WITH_OPENGL=ON \-D BUILD_opencv_ts=OFF \-D OPENCV_ENABLE_NONFREE=ON \..

参数详解：

CMAKE_BUILD_TYPE=Release：发布版本，开启编译优化，速度更快。
CMAKE_INSTALL_PREFIX=/usr/local：安装到 /usr/local，供全局使用。
OPENCV_EXTRA_MODULES_PATH：指向 opencv_contrib/modules，启用扩展模块。
BUILD_EXAMPLES：编译官方示例，帮助学习。
BUILD_opencv_python3=ON：生成 Python3 接口。
ENABLE_NEON=ON：启用 ARM NEON 优化（在 Raspberry Pi 上有用）。
WITH_TBB=ON：启用 Intel TBB 多线程加速。
WITH_V4L=ON：启用视频采集。
OPENCV_ENABLE_NONFREE=ON：启用 SIFT/SURF 等非自由算法（仅在需要时开启）。

如出现依赖缺失，会提示缺少的 dev 库名称，按提示用 sudo apt-get install <缺少的库> 即可。

4. 编译与安装

并行编译（4 核 CPU 为例，可根据实际修改 -j4）：
```
make -j4
```
- 编译时间：根据机器性能，一般在 10~30 分钟之间。
- 如果编译过程中报错，查看报错信息，根据提示安装缺失依赖再运行 make。
安装
```
sudo make install
sudo ldconfig
```
- make install 会将编译好的库、头文件、Python 模块等安装到 /usr/local/。
- ldconfig 更新系统库缓存，确保新库可被链接。

5. 验证安装

C++ 测试
- 参考上文 Ubuntu apt-get 验证方法，使用 pkg-config：
```
pkg-config --modversion opencv4
```
  若返回 4.8.0（或你编译时的版本号），说明正确识别。
- 编写同样的 main.cpp，然后：
```
g++ main.cpp -o test `pkg-config --cflags --libs opencv4`
./test
```

Python 测试

打开 Python3 交互式，执行：

python3
>>> import cv2
>>> cv2.__version__
'4.8.0'
>>> img = cv2.imread("test.jpg")
>>> cv2.imshow("img", img)
>>> cv2.waitKey(0)
>>> cv2.destroyAllWindows()

若能正常 import cv2，版本号正确，且能够调用 GUI 函数，则编译安装成功。

注意：若 Python import 失败，可能是在多个 Python 环境中出现混淆，可使用 python3 -m pip install numpy 或者检查 cv2.so 是否在 /usr/local/lib/python3.x/dist-packages/ 下。

树莓派（Raspberry Pi）下安装 OpenCV

树莓派（Raspberry Pi）是一款非常适合学习计算机视觉和物联网项目的廉价嵌入式开发板。虽然性能有限，但借助 OpenCV 和 Raspberry Pi 相机模组（或 USB 摄像头），也能完成大量有趣的项目。本节重点介绍如何在树莓派上安装 OpenCV。

一、准备树莓派硬件与系统

硬件准备
- Raspberry Pi 4（推荐 4GB/8GB 内存版，树莓派 3 也可，但编译时间更长）。
- microSD 卡：容量 ≥16GB，建议使用 UHS-I 高速卡。
- 电源适配器：5V/3A（树莓派 4 推荐）。
- 外部显示器、键盘、鼠标：用于初次系统配置。
- USB 摄像头 或 Raspberry Pi Camera Module V2（可选，用于测试摄像头功能）。
系统安装
- 下载 Raspberry Pi OS（64 位推荐）镜像：
  
  https://www.raspberrypi.com/software/operating-systems/
- 使用 Raspberry Pi Imager 将镜像写入 microSD 卡。
- 将 SD 卡插入树莓派，接好显示器、键盘、鼠标、电源线，启动后完成系统首次配置（连接 Wi-Fi、更新系统）。
- 系统更新：
```
sudo apt-get update
sudo apt-get upgrade -y
```
- 打开摄像头接口（若使用 Pi Camera）：
```
sudo raspi-config
# 选择 Interface Options → Camera → Enable
# 然后重启
sudo reboot
```

提示：初次使用终端不熟悉的同学，可以先学习一些 Linux 基础命令，如 ls, cd, cp, mv, rm, sudo 等。

二、使用 apt-get 直接安装

Raspberry Pi OS 自带的源中，有配套 OpenCV 的二进制包，安装方法与 Ubuntu 类似：

sudo apt-get install -y libopencv-dev python3-opencv

安装 C++ 接口与 Python 接口
- libopencv-dev：C++ 开发包
- python3-opencv：Python3 接口

验证 C++ 接口

新建测试目录：

mkdir ~/opencv_pi_test && cd ~/opencv_pi_test

编写 main.cpp：

#include <opencv2/opencv.hpp>
#include <iostream>int main() {cv::Mat img = cv::Mat::zeros(200, 400, CV_8UC3);cv::putText(img, "Rpi OpenCV", cv::Point(50, 100),cv::FONT_HERSHEY_SIMPLEX, 1.0, cv::Scalar(255, 0, 0), 2);cv::imshow("PiTest", img);cv::waitKey(0);return 0;
}

编译并运行：
```
g++ main.cpp -o test `pkg-config --cflags --libs opencv4`
./test
```
- 若能正常打开窗口并显示文字，说明 C++ 部分正常。

验证 Python 接口

python3
>>> import cv2
>>> print(cv2.__version__)
4.x.x
>>> img = cv2.imread("test.jpg")
>>> cv2.imshow("img", img)
>>> cv2.waitKey(0)
>>> cv2.destroyAllWindows()

如果无法弹出窗口，请检查是否在 SSH 终端中运行。需要在本地桌面环境运行，或使用 cv2.imwrite("out.jpg", img) 保存后查看。

缺点：apt-get 安装的版本多数较旧，可能缺少新版模块和性能优化项。如果需要更高性能、更灵活功能，建议从源码编译。

三、从源码编译安装（性能优化）

树莓派性能有限，源码编译时间较长（一次完整编译可能需要 2–4 小时）。但能开启 NEON、V4L、TBB、GTK 等模块，对树莓派摄像头优化显著。以下以 OpenCV 4.8.0 编译为例：

1. 安装依赖

sudo apt-get update
sudo apt-get install -y build-essential cmake git pkg-config \libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavformat-dev \libswscale-dev libv4l-dev libxvidcore-dev libx264-dev libgtk-3-dev \libatlas-base-dev libhdf5-dev libprotobuf-dev protobuf-compiler \libgoogle-glog-dev libgflags-dev python3-dev python3-numpy

特别注意：

libatlas-base-dev：线性代数加速。
libv4l-dev：视频捕获接口（Pi Camera 也需此支持）。
libgtk-3-dev：GUI 窗口。若仅做无窗口脚本可忽略。

2. 获取源码

cd ~
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git

也可切到指定版本分支或 tag，例如：

cd ~/opencv
git checkout 4.8.0
cd ../opencv_contrib
git checkout 4.8.0

3. 配置编译

cd ~/opencv
mkdir build && cd buildcmake -D CMAKE_BUILD_TYPE=Release \-D CMAKE_INSTALL_PREFIX=/usr/local \-D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \-D BUILD_EXAMPLES=ON \-D WITH_TBB=OFF \               # 树莓派通常不开启 TBB，加快编译-D WITH_V4L=ON \-D WITH_QT=OFF \-D WITH_OPENGL=ON \-D ENABLE_NEON=ON \-D BUILD_opencv_python3=ON \-D OPENCV_ENABLE_NONFREE=ON \-D BUILD_DOCS=OFF \-D BUILD_TESTS=OFF \-D BUILD_PERF_TESTS=OFF \..

ENABLE_NEON=ON：启用 ARM NEON 优化。
WITH_TBB=OFF：关闭 TBB，以免编译失败。
WITH_OPENGL=ON：若用 OpenGL 渲染。
其他同 Ubuntu 源码配置。

4. 编译与安装

make -j4  # 如果是树莓派 4，默认 4 核并行
sudo make install
sudo ldconfig

编译时间：2–4 小时不等。耐心等待。
若过程中报错，可根据缺少的依赖名称安装补充。

5. 验证安装与摄像头测试

C++ 测试
- 同 Ubuntu 步骤，用 pkg-config 验证版本：
```
pkg-config --modversion opencv4
```
  若返回 4.8.0 或对应版本号，即可进行示例编译。

Python 测试

python3
>>> import cv2
>>> print(cv2.__version__)
'4.8.0'
>>> cap = cv2.VideoCapture(0)
>>> ret, frame = cap.read()
>>> cv2.imshow("Cam", frame)
>>> cv2.waitKey(0)
>>> cap.release()
>>> cv2.destroyAllWindows()

若使用 Pi Camera，需要先安装 python3-picamera 并配置 opencv 支持。

摄像头测试（USB 摄像头或 Pi Camera）

USB 摄像头：只要 VideoCapture(0) 即可访问。

Pi Camera：

安装 picamera 支持：

sudo apt-get install -y python3-picamera

测试代码（Python）：

import cv2
from picamera.array import PiRGBArray
from picamera import PiCamera
import timecamera = PiCamera()
camera.resolution = (640, 480)
rawCapture = PiRGBArray(camera, size=(640, 480))
time.sleep(0.1)for frame in camera.capture_continuous(rawCapture, format="bgr", use_video_port=True):image = frame.arraycv2.imshow("PiCam", image)rawCapture.truncate(0)if cv2.waitKey(1) & 0xFF == ord('q'):breakcamera.close()
cv2.destroyAllWindows()

运行：
```
python3 pi_camera_test.py
```
- 画面出现后，按 q 键退出。

至此，树莓派平台上的 OpenCV 安装与测试完成！

常见问题及故障排查

本节汇总一些各平台常见的安装错误与解决方案，帮小白迅速定位问题。

1. 环境变量不生效

现象：Windows 上在 CMD 中输入 opencv_version 提示命令未找到；运行 exe 报错找不到 *.dll。
检查：
1. 确认是否在 “系统变量” 而非 “用户变量” 中添加 PATH。
2. 重新打开一个新的 CMD/PowerShell 窗口，环境变量变更才会生效。
3. PATH 中的路径是否拼写正确，没有多余空格或反斜杠。
解决方案：
- 重新编辑环境变量，复制粘贴完整路径后确定。
- 在命令行输入 echo %PATH% 或 echo $Env:Path（PowerShell）检查是否包含 C:\opencv\build\x64\vc15\bin。

2. CMake 找不到依赖

现象：在 Ubuntu/树莓派源码编译时，运行 cmake 报类似 “Could NOT find GTK3 (missing: GTK3_X11_INCLUDE_DIR)” 或 “Could NOT find libjpeg” 等错误。
检查与解决：
1. 从提示信息中提取关键缺失库名称，例如 GTK3_X11_INCLUDE_DIR，使用 sudo apt-get install libgtk-3-dev。
2. 若缺少图像编解码支持，安装对应 dev 包：
```
sudo apt-get install -y libjpeg-dev libpng-dev libtiff-dev
```
3. 安装视频 I/O 相关依赖：
```
sudo apt-get install -y libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
```
4. 重新运行 cmake，直到没有依赖缺失的警告。

3. Python 导入失败

现象：import cv2 报 ModuleNotFoundError: No module named 'cv2'。
原因：可能同时有多个 Python 版本，cv2 安装到了其它环境；或者源码编译时 Python 环境不一致。
解决：
1. 确保使用的是系统默认 Python3，输入 which python3 查看路径。
2. 再次安装 numpy：
```
python3 -m pip install --user numpy
```
3. 确认 cv2 模块文件是否在 Python site-packages 中：
```
python3 -c "import sys; print([p for p in sys.path if 'site-packages' in p])"
ls /usr/local/lib/python3.*/dist-packages | grep cv2
```
4. 若编译后没有生成 cv2.so，可尝试重新编译并确认 BUILD_opencv_python3=ON。

4. 编译报错“缺少 xxx 库”

现象：在 Windows/Ubuntu/树莓派上从源码编译时，make 过程中提示 “undefined reference to <某个函数>”、“找不到 <某个库>” 等。
可能原因 & 解决思路：
1. Windows：
  - 检查 Visual Studio 扩展是否完整安装，确保 C++ 桌面开发工作负载已勾选。
  - 检查 CMake 文件中指定的 OPENCV_EXTRA_MODULES_PATH 是否正确。
  - 确认是否遗漏 dll/lib 目录或连接错误。
2. Ubuntu/树莓派：
  - 查找提示的缺少库名称和对应的 dev 包，例如如果报缺少 protobuf，则：
```
sudo apt-get install -y libprotobuf-dev protobuf-compiler
```
  - 若提示缺少 Python 头文件，确保已安装 python3-dev。
  - 有时需要先卸载系统自带 OpenCV：
```
sudo apt-get purge libopencv*
sudo apt-get autoremove
```
    然后再编译安装。

总之，遇到编译错误时，仔细阅读报错信息中的关键词（库名、函数名），在网上搜索对应的缺失包名，然后执行 apt-get 安装即可。对新手来说，依赖安装是最常见的环节，多试几次就熟悉了。

总结与扩展阅读

至此，你已经掌握了在 Windows/Ubuntu/树莓派 上 “从零开始” 安装与配置 OpenCV 的全过程。无论是直接使用预编译包，还是从源码编译定制，都涉及到了如下关键步骤：

环境准备：编译工具、依赖库、Python 环境。
获取 OpenCV：选择预编译版本或克隆源码。
配置 & 编译：CMake 参数设置、make 并行编译、安装与 ldconfig。
环境变量 & 依赖管理：确保系统能找到 DLL/SO 库、Python 能找到 cv2 模块。
验证安装：用最简单的 “Hello OpenCV” 代码测试窗口显示与图像处理功能。
常见问题排查：环境变量、CMake 缺失依赖、Python 路径混淆、编译报错缺少库等。

持续学习与扩展

官方文档：
- OpenCV 官网文档（C++）：https://docs.opencv.org/
- OpenCV Python 教程：https://docs.opencv.org/4.x/d6/d00/tutorial_py_root.html
经典书籍：
- 《Learning OpenCV 4 Computer Vision with Python 3》
- 《OpenCV 4 with C++ Blueprints》
示例项目：
- GitHub 上搜索 “awesome-opencv” 了解各类示例与实践项目。
- 在树莓派上尝试人脸识别、物体跟踪、机器学习模型的推理等。
社区资源：
- Stack Overflow（中英双语），随时搜索具体问题的解决方案。
- CSDN、博客园等国内技术博客，大量教程与心得。