小白也能看懂！OpenCV 从零开始安装配置全教程（包含Windows / Ubuntu / 树莓派）系统详细操作配置教程
摘要
本教程是面向“小白也能懂”的OpenCV安装与配置全攻略，涵盖Windows、Ubuntu和树莓派三大平台，真正实现“从零开始”快速上手。文章详细讲解了OpenCV下载安装教程、OpenCV安装、Ubuntu安装OpenCV、树莓派安装OpenCV等步骤，手把手指导小白用户进行环境准备、依赖库安装、解压与环境变量配置、CMake编译、源码编译与apt-get安装等操作。通过本教程，小白也能一步步完成OpenCV安装配置，为后续图像处理与计算机视觉项目开发打下坚实基础。
目录
前言
准备工作与基础知识
什么是 OpenCV？为什么要学习 OpenCV？运行环境与系统要求 Windows 下安装 OpenCV
环境准备下载 OpenCV 安装包解压与配置环境变量配置 Visual Studio/MinGW 编译环境验证安装（Hello OpenCV） Ubuntu 下安装 OpenCV
环境准备从 apt-get 安装（推荐快速入门）从源码编译安装（适合高级定制）验证安装（Python 与 C++ 示例） 树莓派（Raspberry Pi）下安装 OpenCV
准备树莓派硬件与系统使用 apt-get 直接安装从源码编译安装（性能优化）验证安装与摄像头测试 常见问题及故障排查
环境变量不生效CMake 找不到依赖Python 导入失败编译报错“缺少 xxx 库” 总结与扩展阅读
前言
本教程专为从未接触过图像处理、编译配置的小白用户打造。我们将带你“从零开始”，逐步完成在不同系统（Windows、Ubuntu、树莓派）上安装和配置 OpenCV（Open Source Computer Vision Library）的全过程。只要你跟着步骤走，即使对命令行、编译环境、依赖库一无所知，也能轻松完成安装。
目标读者：零基础学习者、对图像处理感兴趣的同学、想动手搭建计算机视觉开发环境的初学者。
教程亮点：
详细步骤图文结合（文字详尽说明）。包含常见报错及解决方案。Windows、Ubuntu、树莓派三大平台全覆盖。关键词标注，让你快速检索 “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 个系统，下面分别说明各自的最小要求，供小白用户简单确认。
平台最低要求（推荐）WindowsWindows 10（64 位），4 GB 内存以上，至少 10 GB 硬盘空间UbuntuUbuntu 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 toolsCMake 工具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
#include
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
#include
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
#include
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 build
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 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 time
camera = 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.array
cv2.imshow("PiCam", image)
rawCapture.truncate(0)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
camera.close()
cv2.destroyAllWindows()
运行：
python3 pi_camera_test.py
画面出现后，按 q 键退出。
至此，树莓派平台上的 OpenCV 安装与测试完成！
常见问题及故障排查
本节汇总一些各平台常见的安装错误与解决方案，帮小白迅速定位问题。
1. 环境变量不生效
现象：Windows 上在 CMD 中输入 opencv_version 提示命令未找到；运行 exe 报错找不到 *.dll。
检查：
确认是否在 “系统变量” 而非 “用户变量” 中添加 PATH。重新打开一个新的 CMD/PowerShell 窗口，环境变量变更才会生效。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” 等错误。
检查与解决：
从提示信息中提取关键缺失库名称，例如 GTK3_X11_INCLUDE_DIR，使用 sudo apt-get install libgtk-3-dev。
若缺少图像编解码支持，安装对应 dev 包：
sudo apt-get install -y libjpeg-dev libpng-dev libtiff-dev
安装视频 I/O 相关依赖：
sudo apt-get install -y libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
重新运行 cmake，直到没有依赖缺失的警告。
3. Python 导入失败
现象：import cv2 报 ModuleNotFoundError: No module named 'cv2'。
原因：可能同时有多个 Python 版本，cv2 安装到了其它环境；或者源码编译时 Python 环境不一致。
解决：
确保使用的是系统默认 Python3，输入 which python3 查看路径。
再次安装 numpy：
python3 -m pip install --user numpy
确认 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
若编译后没有生成 cv2.so，可尝试重新编译并确认 BUILD_opencv_python3=ON。
4. 编译报错“缺少 xxx 库”
现象：在 Windows/Ubuntu/树莓派上从源码编译时，make 过程中提示 “undefined reference to <某个函数>”、“找不到 <某个库>” 等。
可能原因 & 解决思路：
Windows：
检查 Visual Studio 扩展是否完整安装，确保 C++ 桌面开发工作负载已勾选。检查 CMake 文件中指定的 OPENCV_EXTRA_MODULES_PATH 是否正确。确认是否遗漏 dll/lib 目录或连接错误。 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、博客园等国内技术博客，大量教程与心得。
请将本教程保存至你常用的笔记工具，转发给同学或网友，让更多 “零基础的小白” 能够快速开启计算机视觉之旅。如果在安装过程中遇到任何问题，欢迎留言交流，我们一起排查解决！
祝你学习顺利，早日完成第一个 OpenCV 项目！ 用心阅读、动手实践，你一定能从“小白”变成“小高手”！