小白也能看懂！OpenCV 從零開始安裝配置全教程（包含Windows / Ubuntu / 樹莓派）系統詳細操作配置教程

摘要

本教程是面向“小白也能懂”的OpenCV安裝與配置全攻略，涵蓋Windows、Ubuntu和樹莓派三大平臺，真正實現“從零開始”快速上手。文章詳細講解了OpenCV下載安裝教程、OpenCV安裝、Ubuntu安裝OpenCV、樹莓派安裝OpenCV等步驟，手把手指導小白用戶進行環境準備、依賴庫安裝、解壓與環境變量配置、CMake編譯、源碼編譯與apt-get安裝等操作。通過本教程，小白也能一步步完成OpenCV安裝配置，為后續圖像處理與計算機視覺項目開發打下堅實基礎。

前言
準備工作與基礎知識
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、博客園等國內技術博客，大量教程與心得。