🤖 零基礎學 OpenCV！VSCode & PyCharm 雙配置全攻略

新手必看！VSCode&PyCharm 配置 OpenCV 超詳細教程（支持 Python 和 C++ 雙語言）#

適用對象：初學者，希望在 VSCode 與 PyCharm 兩款常用 IDE 中，學會配置並使用 OpenCV，分別實現 Python 與 C++ 環境的快速上手。
適用平台：Windows 10/11（本文以 Windows 為主要示範，Linux 或 macOS 用戶可參照各自系統的包管理細節進行適當調整）。

摘要#

本文為新手用戶提供了最全的 VSCode & PyCharm 配置 OpenCV 教程，涵蓋 Python 與 C++ 雙語言環境搭建與調試流程。文章詳細介紹了在 Windows 系統下安裝 Python、Visual Studio Build Tools、CMake、OpenCV 預編譯包，並手把手演示如何在 VSCode 中創建虛擬環境、安裝 opencv-python、配置 CMakeLists.txt、生成並運行 C++ 示例程序。快速實現圖像讀取、灰度轉換、窗口顯示等基礎操作，為後續計算機視覺開發打下堅實基礎。

新手必看！VSCode&PyCharm 配置 OpenCV 超詳細教程（支持 Python 和 C++ 雙語言）

目錄#

環境準備
1.1. 系統要求
1.2. 工具下載與安裝概覽
Python + VSCode 環境配置
2.1. 安裝 Python
2.2. 創建並激活虛擬環境
2.3. 安裝 VSCode 及 Python 插件
2.4. 安裝 OpenCV（Python 版）
2.5. 在 VSCode 中創建、配置項目
2.6. 編寫並運行 Python 示例腳本
C++ + VSCode 環境配置
3.1. 安裝 C++ 編譯工具（Windows：Visual Studio Build Tools）
3.2. 下載並配置 OpenCV 預編譯包
3.3. 安裝 VSCode C/C++ 擴展
3.4. 在 VSCode 中創建 C++ 項目（CMake + 示例代碼）
3.5. 配置 c_cpp_properties.json、tasks.json 與 launch.json
3.6. 編譯並運行 C++ 示例程序
Python + PyCharm 環境配置
4.1. 安裝 PyCharm
4.2. 創建 Python 項目並選擇解釋器
4.3. 在 PyCharm 中安裝 OpenCV（Python 版）
4.4. 編寫並運行 Python 示例腳本
C++ + PyCharm 環境配置
5.1. PyCharm 對 C++ 支持說明
5.2. 利用 CMake 構建 C++ 項目並使用終端/外部工具
5.3. 在 PyCharm 中運行與調試 C++ 示例
常見問題與解決方案
附錄
7.1. Windows 環境變量簡要說明
7.2. CMakeLists.txt 詳細示例
7.3. 快速回顧

環境準備#

1.1 系統要求#

操作系統：Windows 10/11（建議 64 位）。
磁盤空間：至少 10 GB 可用空間，用於安裝 IDE、編譯工具與 OpenCV 庫。
內存：至少 8 GB，編譯 C++ 源碼時盡量保證運行流暢。
網絡：可正常訪問外網，用於下載 Python 包、OpenCV 預編譯包等。

提示：如果你使用的是 Linux 或 macOS，Python 部分幾乎一致；C++ 部分請改用相應系統的包管理（比如 Linux 下用 apt 或 yum 安裝 libopencv-dev，macOS 下用 Homebrew brew install opencv），VSCode 與 PyCharm 的配置思路相同，但路徑與命令略有不同，請自行替換。

1.2 工具下載與安裝概覽#

安裝順序建議：

安裝 Python，把“Add Python 3.x to PATH”勾選上（方便後續在終端直接使用 python 命令）。

安裝 Visual Studio Build Tools，並在安裝過程中勾選 “C++ build tools” 與 “Windows 10/11 SDK”。

安裝 VSCode 與 PyCharm。

下載並解壓 OpenCV 預編譯包。

按照下面章節的步驟，分別配置 Python 與 C++ 環境。

Python + VSCode 環境配置#

本節將帶你從零開始，在 Windows 平台上搭建基於 VSCode 的 Python + OpenCV 開發環境，並運行一個簡單圖像讀取與顯示示例。

2.1 安裝 Python#

下載 Python 安裝包
- 訪問 Python 官網，點擊最新 3.x 版本（例如 Python 3.11.x）的 Windows Installer（根據自己系統選擇 64-bit）。
運行安裝程序
- 勾選頁面底部的 “Add Python 3.x to PATH”，然後點擊 “Install Now”。
- 等待安裝完成。
驗證安裝
- 打開 命令提示符 (CMD) 或 PowerShell，輸入：
```
1
python --version
```
  若顯示類似 Python 3.11.x，說明安裝成功。
- 同時也可以驗證 pip：
```
1
pip --version
```
  若顯示 pip 23.x.x from ...，表示 pip 可用。

2.2 創建並激活虛擬環境#

為了保證項目依賴獨立，建議使用虛擬環境（venv）。

打開 命令提示符 (CMD) 或 PowerShell，進入你希望存放項目的文件夾，例如：
```
1
cd C:\Users\你的用戶名\Projects
2
mkdir OpenCV_VSCode_Python
3
cd OpenCV_VSCode_Python
```
創建虛擬環境：
```
1
python -m venv venv
```
這會在當前文件夾下創建一個名為 venv 的子文件夾，里面包括獨立的 Python 解釋器。
激活虛擬環境：
- 在 命令提示符：
```
1
venv\Scripts\activate.bat
```
- 在 PowerShell（可能需要先解除腳本執行限制）：
```
1
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
2
.\venv\Scripts\Activate.ps1
```
- 激活後，終端提示符會出現前綴 (venv)。

注意：後續所有在終端執行的 pip install、python 命令，都將在該虛擬環境中生效。如需退出虛擬環境，輸入 deactivate 即可。

2.3 安裝 VSCode 及 Python 插件#

下載 VSCode
- 訪問 VSCode 官網，點擊下載適用於 Windows 的安裝程序。
- 安裝時勾選 “Add to PATH”、“Register Code as Editor for supported file types” 等選項（方便後續直接在資源管理器右鍵打開）。
打開 VSCode
- 安裝完成後，雙擊運行 VSCode。
安裝 Python 插件
- 在左側擴展圖標（Extensions）中，搜索 “Python”，由 Microsoft 發布的官方擴展為：
```
1
Python (ms-python.python)
```
- 點擊 “Install” 進行安裝。
- 安裝完畢後，VSCode 底部狀態欄會出現已識別的 Python 解釋器選項。

2.4 安裝 OpenCV（Python 版）#

確保虛擬環境已激活
- 如果之前已經退出，重新打開項目目錄，在終端中重新激活：
```
1
cd C:\Users\你的用戶名\Projects\OpenCV_VSCode_Python
2
venv\Scripts\activate.bat
```
安裝 OpenCV-Python 包
- 在終端輸入：
```
1
pip install opencv-python opencv-contrib-python
```
- 解釋：
  - opencv-python：主模塊，包含核心功能。
  - opencv-contrib-python：包含額外的算法模塊（contrib），推薦同時安裝。
驗證安裝
- 在終端啟動 Python 交互：
```
1
python
```
- 在交互式命令行輸入：
```
1
import cv2
2
print(cv2.__version__)
```
- 如果輸出類似 4.8.0 或者其他版本號，就說明安裝成功。
- 輸入 exit() 退出 Python 交互。

2.5 在 VSCode 中創建、配置項目#

打開項目文件夾
- 在 VSCode 中，依次點擊：文件 → 打開文件夾…，選擇剛才創建的 C:\Users\你的用戶名\Projects\OpenCV_VSCode_Python 文件夾。
選擇 Python 解釋器
- 在 VSCode 窗口的右下角，會顯示當前默認的 Python 解釋器。如果它還不是 venv 中的解釋器：
  - 點擊右下角“Python 版本號”，在彈出的“Python 選擇解釋器”列表里，選擇以 venv 路徑開頭的那個項（例如 C:\...\OpenCV_VSCode_Python\venv\Scripts\python.exe）。
創建示例腳本文件
- 在項目根目錄下，點擊左側資源管理器里的“新建文件”，命名為 opencv_test.py。
自動補全 / IntelliSense 檢查
- 打開 opencv_test.py，輸入：
```
1
import cv2
2

3
# 測試 OpenCV 是否可用
4
img = cv2.imread('test.jpg')
5
cv2.imshow('Test Window', img)
6
cv2.waitKey(0)
7
cv2.destroyAllWindows()
```
- 如果 import 時沒有紅線報錯，說明 VSCode 已經正確識別 cv2 模塊。

注意：示例中使用 cv2.imshow 需要在 Windows 本地環境執行，且要確保當前目錄下存在名為 test.jpg 的圖像文件。可以自行下載一張測試圖片命名為 test.jpg 放在項目根目錄。

2.6 編寫並運行 Python 示例腳本#

準備測試圖像
- 在項目根目錄下，新建一個名為 test.jpg 的圖像（任意一張照片即可）。

完整示例代碼（opencv_test.py）：

1
import cv2
2

3
def main():
4
    # 讀取本目錄下的 test.jpg
5
    img = cv2.imread('test.jpg')
6
    if img is None:
7
        print('無法讀取 test.jpg，請確認文件存在於當前目錄')
8
        return
9

10
    # 將圖像轉換為灰度並顯示
11
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
12

13
    cv2.imshow('原圖', img)
14
    cv2.imshow('灰度圖', gray)
15

16
    print('按任意鍵關閉窗口...')
17
    cv2.waitKey(0)
18
    cv2.destroyAllWindows()
19

20
if __name__ == '__main__':
21
    main()

在 VSCode 中執行
- 打開 opencv_test.py，可以點擊右上方的綠色運行按鈕（▶），或者在終端中手動輸入：
```
1
python opencv_test.py
```
- 如果成功，會分別彈出兩個窗口：一個顯示彩色原圖，一個顯示灰度圖。終端會打印 按任意鍵關閉窗口...。按任意鍵後，窗口關閉，程序結束。

至此，Python + VSCode + OpenCV 環境配置完成！

C++ + VSCode 環境配置#

本節將介紹如何在 Windows 平台下，通過 VSCode + CMake + MSVC 構建並使用 OpenCV C++ 庫，詳細說明下載預編譯包、設置環境變量、配置 VSCode 對 C++ 的編譯與調試等步驟。

3.1 安裝 C++ 編譯工具（Windows：Visual Studio Build Tools）#

下載
- 訪問 Visual Studio 官網下載頁，向下滾動到 “Tools for Visual Studio 2022” 部分，找到 “Build Tools for Visual Studio 2022” 並點擊下載。
安裝
- 運行下載得到的 vs_BuildTools.exe 安裝程序。
- 選擇工作負載（Workloads）：勾選 “使用 C++ 的桌面開發”（Desktop development with C++），確保下方包含：
  - MSVC v143 或 v142 – VS 2022 C++ x64/x86 構建工具
  - Windows 10 或 11 SDK
  - CMake 工具
- 點擊右下角 “Install”；等待下載並安裝，安裝過程大約需要 5 GB 空間與數分鐘時間。
驗證
- 安裝完成後，打開 x64 Native Tools Command Prompt for VS 2022（在「開始菜單 → Visual Studio 2022」中即可找到）。
- 輸入：
```
1
cl
```
  如果出現 Microsoft (R) C/C++ Optimizing Compiler 等輸出，則說明 MSVC 已就緒。
- 同時驗證 CMake：
```
1
cmake --version
```
  如果輸出類似 cmake version 3.27.x，說明 CMake 安裝成功。

3.2 下載並配置 OpenCV 預編譯包#

下載 OpenCV Windows 預編譯包
- 訪問 OpenCV Releases（或在瀏覽器搜索 “OpenCV releases”），找到最新的 Windows 預編譯版本，例如 OpenCV 4.8.0。
- 下載 .exe 安裝包（例如 opencv-4.8.0-vc14_vc15.exe）或者 .zip 包。
解壓/安裝
- 如果下載的是 .exe 安裝包，雙擊運行，選擇安裝目錄（例如 C:\opencv\opencv-4.8.0）。
- 如果下載的是 .zip，右鍵解壓到例如 C:\opencv\opencv-4.8.0。
環境變量配置
- 添加 OPENCV_DIR
  1. 右鍵“此電腦” → “屬性” → “高級系統設置” → “環境變量(N)…”。
  2. 在 “系統變量(S)” 區域，點擊 “新建(W)…”，變量名填 OPENCV_DIR，變量值填：
    1 C:\opencv\opencv-4.8.0\build\x64\vc15 # 根據實際版本和文件夾填寫，通常到 build\x64\vc15
  3. 點擊確定。
- 修改 Path
  1. 在 “系統變量(S)” 區域，找到 Path，選中後點擊 “編輯(I)…”。
  2. 添加一行：
    1 C:\opencv\opencv-4.8.0\build\x64\vc15\bin
  3. 點擊確定，保存退出。
- 驗證（在新的命令提示符中）
```
1
echo %OPENCV_DIR%
```
  若輸出上述路徑，則生效。

說明：

vc15 對應 VS 2017/2019/2022 通用的構建；若你安裝的 OpenCV 版本是基於 VS 2019/2022，則文件夾可能是 vc14/vc15。請根據實際目錄填寫。

build\x64\vc15\bin 下包含了各類 .dll 動態庫，以及 opencv_world480.dll（單一 DLL）或多個 opencv_*.dll。

3.3 安裝 VSCode C/C++ 擴展#

打開 VSCode
- 如果還未運行 VSCode，請雙擊打開。
安裝 C/C++ 擴展
- 在左側擴展市場 (Extensions) 中，搜索：
```
1
C/C++
```
- 由 Microsoft 發布的官方擴展“C/C++” (ms-vscode.cpptools) 位於搜索結果第一。
- 點擊 “Install” 進行安裝。
安裝 CMake Tools 擴展（可選，但強烈推薦）
- 在擴展市場搜索：
```
1
CMake Tools
```
- 由 Microsoft 發布的 “CMake Tools” (ms-vscode.cmake-tools) 拓展可以讓 VSCode 本身識別 CMake 項目、自動生成配置，便於日後管理覆雜項目。
- 點擊 “Install” 安裝。

小提醒：

安裝完畢後，VSCode 右下角會出現 “CMake: [未激活/Kit: None]” 的字樣，表示已加載 CMake Tools。

CMake Tools 能自動檢測系統中的 CMake、編譯器（如 MSVC），並允許你通過 GUI 直接選擇 “配置”、“生成”、“編譯”等操作。

3.4 在 VSCode 中創建 C++ 項目（CMake + 示例代碼）#

下面以 CMake 構建示例講解如何集成 OpenCV。

新建項目文件夾
- 在你喜歡的位置（例如 C:\Users\你的用戶名\Projects\OpenCV_VSCode_CPP）創建文件夾：
```
1
mkdir C:\Users\你的用戶名\Projects\OpenCV_VSCode_CPP
2
cd C:\Users\你的用戶名\Projects\OpenCV_VSCode_CPP
```
準備項目結構
- 在 OpenCV_VSCode_CPP 目錄下，新建以下文件/文件夾結構：
```
1
OpenCV_VSCode_CPP
2
├── CMakeLists.txt
3
├── src
4
│   └── main.cpp
5
└── image
6
    └── test.jpg
```
- 其中：
  - CMakeLists.txt：CMake 構建配置文件。
  - src/main.cpp：C++ 示例代碼文件。
  - image/test.jpg：測試用圖像。可自行準備一張照片並放置其中。

編寫 CMakeLists.txt
在項目根目錄（OpenCV_VSCode_CPP）新建 CMakeLists.txt，內容示例如下（請根據你的 OpenCV 版本與文件夾路徑自行替換 OPENCV_DIR）：

1
cmake_minimum_required(VERSION 3.10)
2
project(OpenCV_VSCode_CPP)
3

4
# 設置 C++ 標準（此處為 C++17，可自定義）
5
set(CMAKE_CXX_STANDARD 17)
6
set(CMAKE_CXX_STANDARD_REQUIRED ON)
7

8
# 查找 OpenCV 包
9
# OPENCV_DIR 環境變量已在系統中定義，指向 C:/opencv/opencv-4.8.0/build/x64/vc15
10
find_package(OpenCV REQUIRED)
11

12
# 輸出包含目錄（可選，便於在編譯輸出中查看）
13
message(STATUS "OpenCV include dirs: ${OpenCV_INCLUDE_DIRS}")
14
message(STATUS "OpenCV libraries: ${OpenCV_LIBS}")
15

16
# 添加可執行文件
17
add_executable(${PROJECT_NAME} src/main.cpp)
18

19
# 鏈接 OpenCV 庫
20
target_link_libraries(${PROJECT_NAME} PRIVATE ${OpenCV_LIBS})

說明：

find_package(OpenCV REQUIRED)：依賴於環境變量 OPENCV_DIR，CMake 會在 {OPENCV_DIR}/x64/vc15/lib/cmake/opencv4 下尋找相關配置。

${OpenCV_INCLUDE_DIRS} 包含了 include 文件夾的路徑，比如 C:/opencv/opencv-4.8.0/build/include。

${OpenCV_LIBS} 包含了所有需要鏈接的 .lib 文件（靜態鏈接或動態鏈接均由 CMake 自動選擇）。

編寫 main.cpp 示例
在 src/main.cpp 中，復制以下代碼：

1
#include <opencv2/opencv.hpp>
2
#include <iostream>
3

4
int main() {
5
    // 構造圖像路徑（相對路徑：工程目錄/image/test.jpg）
6
    std::string image_path = "../image/test.jpg";
7
    cv::Mat img = cv::imread(image_path);
8
    if (img.empty()) {
9
        std::cerr << "無法打開圖像: " << image_path << std::endl;
10
        return -1;
11
    }
12

13
    cv::Mat gray;
14
    cv::cvtColor(img, gray, cv::COLOR_BGR2GRAY);
15

16
    cv::imshow("原圖 (Color)", img);
17
    cv::imshow("灰度圖 (Gray)", gray);
18

19
    std::cout << "按任意鍵退出..." << std::endl;
20
    cv::waitKey(0);
21

22
    cv::destroyAllWindows();
23
    return 0;
24
}

放置測試圖片
- 在 OpenCV_VSCode_CPP/image 文件夾下放置一張 test.jpg。
- 路徑示例：
```
1
C:\Users\你的用戶名\Projects\OpenCV_VSCode_CPP\image\test.jpg
```

3.5 配置 `c_cpp_properties.json`、`tasks.json` 與 `launch.json`#

如果你安裝了 CMake Tools 擴展，可以讓 VSCode 自動生成大部分配置；這里展示手動配置方式，以便理解其原理。若使用 CMake Tools，後續手動配置步驟可略做簡化。

3.5.1 c_cpp_properties.json#

此文件用來告知 VSCode C/C++ 擴展，頭文件搜索路徑（includePath）和 IntelliSense 選項。位置：.vscode/c_cpp_properties.json。

在項目根目錄下新建 .vscode 文件夾，再在其中新建 c_cpp_properties.json，內容示例：

1
{
2
    "configurations": [
3
        {
4
            "name": "Win32",
5
            "includePath": [
6
                "${workspaceFolder}/**",
7
                "C:/opencv/opencv-4.8.0/build/include"
8
            ],
9
            "defines": [
10
                "_DEBUG",
11
                "UNICODE",
12
                "_UNICODE"
13
            ],
14
            "windowsSdkVersion": "10.0.19041.0",
15
            "compilerPath": "C:/Program Files/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.35.32215/bin/Hostx64/x64/cl.exe",
16
            "cStandard": "c11",
17
            "cppStandard": "c++17",
18
            "intelliSenseMode": "windows-msvc-x64"
19
        }
20
    ],
21
    "version": 4
22
}

請根據實際安裝路徑更改：

includePath 中第二行要與 C:\opencv\opencv-4.8.0\build\include 路徑一致。

compilerPath 為 MSVC 編譯器的絕對路徑，可在命令提示符中 where cl.exe 查到，然後複製完整路徑。

windowsSdkVersion 根據你安裝的 Windows SDK 版本填寫，若不知道可以先留空或使用默認，IntelliSense 會自動識別。

3.5.2 tasks.json#

此文件告訴 VSCode 如何調用編譯命令，把 CMake 的生成任務或直接 cl/g++ 編譯語句寫入這里，以便按下“Ctrl+Shift+B”時直接編譯。位置：.vscode/tasks.json。

示例：使用 CMake 編譯

1
{
2
    "version": "2.0.0",
3
    "tasks": [
4
        {
5
            "label": "CMake: Configure",
6
            "type": "shell",
7
            "command": "cmake",
8
            "args": [
9
                "-S",
10
                "${workspaceFolder}",
11
                "-B",
12
                "${workspaceFolder}/build",
13
                "-G",
14
                "NMake Makefiles"
15
            ],
16
            "group": {
17
                "kind": "build",
18
                "isDefault": true
19
            },
20
            "problemMatcher": []
21
        },
22
        {
23
            "label": "CMake: Build",
24
            "type": "shell",
25
            "command": "cmake",
26
            "args": [
27
                "--build",
28
                "${workspaceFolder}/build",
29
                "--config",
30
                "Debug"
31
            ],
32
            "group": "build",
33
            "problemMatcher": []
34
        }
35
    ]
36
}

說明：

-S ${workspaceFolder}：指明 CMakeLists.txt 所在目錄。

-B ${workspaceFolder}/build：生成輸出目錄為 build 文件夾。

-G "NMake Makefiles"：使用 NMake 工具鏈（MSVC）；如果你更喜歡使用 Visual Studio 生成文件，可寫 -G "Visual Studio 17 2022"，但此時 VSCode 下的命令行編譯方式會不同。

“CMake: Configure” 與 “CMake: Build” 兩個任務，可以分別按順序運行，也可綁定到快捷鍵。

如果你不想使用 CMake，而想手動調用 cl.exe 進行編譯，也可寫成：

1
{
2
    "version": "2.0.0",
3
    "tasks": [
4
        {
5
            "label": "Compile main.cpp",
6
            "type": "shell",
7
            "command": "\"C:/Program Files/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.35.32215/bin/Hostx64/x64/cl.exe\"",
8
            "args": [
9
                "/EHsc",
10
                "/I", "C:/opencv/opencv-4.8.0/build/include",
11
                "src\\main.cpp",
12
                "/link",
13
                "/LIBPATH:C:/opencv/opencv-4.8.0/build/x64/vc15/lib",
14
                "opencv_world480.lib"
15
            ],
16
            "group": {
17
                "kind": "build",
18
                "isDefault": true
19
            },
20
            "presentation": {
21
                "reveal": "always"
22
            },
23
            "problemMatcher": "$msCompile"
24
        }
25
    ]
26
}

說明：

指定了 cl.exe 的路徑。

/I 參數加入了 OpenCV 的頭文件目錄。

/link 後面通過 /LIBPATH 指定了 .lib 庫所在目錄。

最後直接鏈接了 opencv_world480.lib（如果你的版本號不同，請替換為相應的 .lib 名稱）。

上述任務執行後，會在項目根目錄生成 main.exe 可執行文件。

3.5.3 launch.json#

此文件用於 VSCode 的調試配置（Debugging），當你按下 F5 或點擊調試時，VSCode 會按照這里的配置啟動程序。位置：.vscode/launch.json。

示例（調試 CMake 生成的可執行文件）

1
{
2
    "version": "0.2.0",
3
    "configurations": [
4
        {
5
            "name": "Debug: OpenCV_Cpp (CMake)",
6
            "type": "cppvsdbg",
7
            "request": "launch",
8
            "program": "${workspaceFolder}/build/Debug/OpenCV_VSCode_CPP.exe",
9
            "args": [],
10
            "stopAtEntry": false,
11
            "cwd": "${workspaceFolder}",
12
            "environment": [],
13
            "console": "externalTerminal",
14
            "preLaunchTask": "CMake: Build"
15
        }
16
    ]
17
}

說明：

program：可執行文件的路徑，請根據你在 CMake 中選擇的生成模式（Debug/Release）和項目名進行修改。

preLaunchTask：在調試前自動執行哪個 Task，此處我們指向了 “CMake: Build”，即每次調試前會自動觸發編譯。

"console": "externalTerminal"：程序調試時使用外部終端彈出窗口，便於使用 cv::imshow 彈窗顯示圖像。

如果你采用手動 cl 編譯方式，則 program 路徑改為 ${workspaceFolder}/main.exe，並將 preLaunchTask 改為你在 tasks.json 中定義的 “Compile main.cpp”。

3.6 編譯並運行 C++ 示例程序#

打開 VSCode，選擇配置
- 點擊右下角的 “Configure CMake Project” 或者 “選擇任務/運行任務”，若你按照上文使用了 CMake Tools 擴展，可直接在 VSCode 右下方的狀態欄找到 “CMake: [Kit: …]” 並選擇你需要的 Kit（如 “Desktop x64”）；然後點擊 “Configure” 讓 CMake 生成工程。
- 如果不使用 CMake Tools 擴展，則可以直接按 Ctrl+Shift+B，選擇 “CMake: Configure” → “CMake: Build”。
生成與編譯
- 使用 CMake Tools：
  - 點擊 VSCode 底部狀態欄 “CMake: [Debug]” → 選擇 “Build”。
  - 等待輸出窗口中出現 “— Build finished” 提示。
- 手動 cl 方式：
  - 按 Ctrl+Shift+B，選擇 “Compile main.cpp” 任務。
  - 等待終端中出現 “main.cpp: …” 編譯信息，並最終生成 main.exe。
調試或運行
- 若要調試，按 F5 或點擊左側活動欄 “Run and Debug” → 選擇 “Debug: OpenCV_Cpp (CMake)”。
- 若僅要運行，直接在 命令提示符、PowerShell 或 VSCode 終端輸入：
```
1
cd build\Debug
2
.\OpenCV_VSCode_CPP.exe
```
  或者：
```
1
cd C:\Users\你的用戶名\Projects\OpenCV_VSCode_CPP
2
main.exe   # 如果你使用手動 cl 編譯
```
- 程序運行後，會彈出兩個窗口：一個顯示彩色圖像 test.jpg，一個顯示灰度圖像，終端會打印 按任意鍵退出...。

注意事項：

如果運行時提示找不到 opencv_world480.dll（或其他版本號），請確認：

已正確將 C:\opencv\opencv-4.8.0\build\x64\vc15\bin 添加到系統 Path。

重新打開 VSCode 或命令提示符，確保環境變量生效。

如果仍報錯，可將 opencv_world480.dll 手動複製到可執行文件所在目錄（build\Debug 或項目根目錄）進行臨時調試。

Python + PyCharm 環境配置#

本節演示如何在 PyCharm 中搭建 Python + OpenCV 環境，流程與 VSCode 類似，但由 PyCharm 自帶的 GUI 操作來完成虛擬環境創建與包管理。

4.1 安裝 PyCharm#

下載
- 訪問 PyCharm 官網，下載社區版（Community）即可，若有教育/工作需要商用高級功能，可選擇 Professional 版。
安裝
- 雙擊下載得到的 pycharm-community-2025.x.exe，一路下一步即可。
- 建議安裝時勾選 “Create Desktop Entry” 以及 “Update PATH variable”，方便後續從命令行啟動。
首次啟動
- 運行 PyCharm，選擇 “Skip Remaining and Set Defaults” 跳過主題、插件等預設，也可以按需自定義。

4.2 創建 Python 項目並選擇解釋器#

啟動 PyCharm
- 在歡迎界面中點擊 “New Project”。
配置項目
- Location：選擇一個項目路徑，例如 C:\Users\你的用戶名\Projects\OpenCV_PyCharm_Python。
- Python Interpreter（關鍵）：
  - PyCharm 默認會使用系統默認 Python，也會讓你創建一個新的虛擬環境。
  - 選擇 “New environment using Virtualenv”，如果你想讓 PyCharm 自動創建並管理虛擬環境。
  - 或者，你也可以選擇 “Existing interpreter”，並指向之前手動創建的 venv：
    1 C:\Users\你的用戶名\Projects\OpenCV_PyCharm_Python\venv\Scripts\python.exe
- 點擊 “Create”。

項目結構

PyCharm 創建後，會在項目根目錄下生成：

1
OpenCV_PyCharm_Python
2
├── .idea
3
└── main.py  # 默認文件，可重命名或刪除

4.3 在 PyCharm 中安裝 OpenCV（Python 版）#

打開 Settings（設置）
- 依次點擊菜單欄：File → Settings…（Windows）或 PyCharm → Preferences…（macOS）。
Project Interpreter 管理
- 在設置框中，左側選擇 Project: OpenCV_PyCharm_Python → Python Interpreter。
- 如果已經有正確的虛擬環境或系統 Python 被選中，在右側會列出當前已安裝的包列表（可能為空）。
- 點擊右側列表上方的 “+” 按鈕，打開 “Available Packages” 搜索框。
搜索並安裝 opencv-python
- 在搜索框中輸入 opencv-python，選中後點擊 “Install Package” 按鈕。
- 等待安裝成功，期間會自動處理依賴。
驗證安裝
- 安裝完成後，點擊 “OK” 或 “Apply” 關閉設置。
- 在項目的 src 目錄（若無可新建一個 src 文件夾），右鍵新建 Python 文件 opencv_test.py，輸入：
```
1
import cv2
2

3
print("OpenCV 版本：", cv2.__version__)
4

5
# 測試讀取並顯示
6
img = cv2.imread('test.jpg')
7
if img is None:
8
    print("無法讀取 test.jpg，請確認文件存在於項目根目錄或指定路徑")
9
else:
10
    cv2.imshow("Show", img)
11
    cv2.waitKey(0)
12
    cv2.destroyAllWindows()
```
- 在項目根目錄放置一張 test.jpg，然後右鍵 opencv_test.py → “Run ‘opencv_test’”。
- 運行後，若終端輸出 OpenCV 版本號並彈窗顯示圖片，說明 Python + OpenCV 在 PyCharm 中配置成功。

4.4 編寫並運行 Python 示例腳本#

項目結構
- 建議將示例腳本都放在 src 或 scripts 文件夾下，並把測試圖像放到項目根目錄，結構示例：
```
1
OpenCV_PyCharm_Python
2
├── .idea
3
├── src
4
│   └── opencv_test.py
5
└── test.jpg
```

示例代碼詳解（src/opencv_test.py）

1
import cv2
2
import sys
3

4
def main():
5
    # 讀取本項目根目錄下的 test.jpg
6
    img = cv2.imread('test.jpg')
7
    if img is None:
8
        print('Error: 無法讀取 test.jpg')
9
        sys.exit(1)
10

11
    # 獲取圖像尺寸（高度、寬度、通道數）
12
    height, width, channels = img.shape
13
    print(f'圖像尺寸：{width}x{height}，通道數：{channels}')
14

15
    # 轉換為灰度圖
16
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
17

18
    # 畫一個矩形框，示範如何使用繪制函數
19
    top_left = (int(width * 0.2), int(height * 0.2))
20
    bottom_right = (int(width * 0.8), int(height * 0.8))
21
    cv2.rectangle(img, top_left, bottom_right, (0, 255, 0), 2)
22

23
    # 顯示原圖與灰度圖
24
    cv2.imshow("原圖 + 矩形框", img)
25
    cv2.imshow("灰度圖", gray)
26

27
    print("按任意鍵關閉窗口...")
28
    cv2.waitKey(0)
29
    cv2.destroyAllWindows()
30

31
if __name__ == "__main__":
32
    main()

運行方式：在 PyCharm 左側項目文件樹，右鍵 opencv_test.py → Run ‘opencv_test’；
觀察控制台打印尺寸信息，窗口會彈出原圖與灰度圖。

至此，Python + PyCharm + OpenCV 環境配置完成！

C++ + PyCharm 環境配置#

PyCharm 對 C/C++ 的支持與 VSCode/CLion 之間有所差異。PyCharm Community 版本本身並不包含原生 C++ 項目模板或強力的 CMake GUI 集成。如果你使用 Professional 版本，也只能得到有限的 CMake 支持。所以，本節將演示一種“在 PyCharm 中使用 CMake + 外部工具 / 終端”來編寫、編譯、運行 C++ + OpenCV 的方法。

5.1 PyCharm 對 C++ 支持說明#

PyCharm Community vs Professional
- Community 版：只針對 Python 開發，有基本的文本編輯功能。可以用作編寫 C++ 代碼的文本編輯器，但沒有內置 CMake 項目模板或調試器。
- Professional 版：具備一定的 CMake 支持（如識別 CMakeLists.txt 並提供語法高亮），但是並不如 CLion 那般完善。
推薦方案
- 對於初學者，若重點還是想在一個 IDE 中同時管理 Python 和 C++，可使用 PyCharm Professional，並利用其對 CMake 的基礎識別。
- 如果你只有 Community 版，依然可以在項目中編寫 C++ 源碼和 CMakeLists.txt，但必須依靠 PyCharm 終端或外部構建工具來完成編譯與調試。
插件
- PyCharm 有第三方插件（如 C/C++），但大多數需要專業版才能生效。此處暫不使用插件，而采用最通用的方式：在 PyCharm 中打開 CMake 項目，配合終端完成編譯、運行、調試。

5.2 利用 CMake 構建 C++ 項目並使用終端/外部工具#

假設你已經安裝了 Visual Studio Build Tools、CMake、並且系統環境變量中包含了 OpenCV 的路徑（參見第 3 章的內容）。下面以一個名為 OpenCV_PyCharm_CPP 的項目演示如何在 PyCharm 中操作。

創建項目
- 打開 PyCharm（Professional 推薦），點擊 “Open”，選擇你在 VSCode 項目中已經創建好的 C:\Users\你的用戶名\Projects\OpenCV_VSCode_CPP 文件夾（或者新建一個獨立同樣結構的項目）。
- PyCharm 會自動識別到一個 CMakeLists.txt 文件，並在右上角顯示 “Load CMake Project” 或 “CMake: [未配置]”。
配置 CMake Profiles（僅 Professional 可見）
- 點擊右上角的 CMake 符號，進入 “CMake Profiles” 設置。
- 新建一個 Profile，命名為 Debug，並指定：
  - CMake executable：系統中可執行的 cmake 路徑（通常在環境變量中已經可用，寫 cmake 即可）。
  - Generator：選擇 NMake Makefiles（與 VSCode 配置保持一致）。
  - CMake Options：如果需要傳入 -DCMAKE_BUILD_TYPE=Debug，可以在此處添加。
- 保存後，PyCharm 會自動使用該 Profile 運行 CMake，生成構建文件。（這一過程可能需要幾秒鐘）
查看生成結果
- CMake 生成的項目文件會位於項目根目錄下或 cmake-build-debug（由 PyCharm 默認創建的構建目錄）。你會在該目錄下看到 .ninja、.ninja_deps、.ninja_log 或者 Makefile、CMakeCache.txt 等文件。
- 如果成功，說明 CMake 已檢測了你的 OpenCV 環境。你可以在 “Event Log” 中看到類似：
```
1
-- OpenCV include dirs: C:/opencv/opencv-4.8.0/build/include
2
-- OpenCV libraries: opencv_world480
```
編譯項目
- Professional 版：
  - 在右上角可以看到一個綠色小錘子圖標（Build）。點擊它，即可執行 CMake 構建。
  - 或者在菜單 Build → Build Project。
- Community 版：
  - PyCharm Community 版無法直接調用 CMake 構建。此時，你需要在 PyCharm 內置 Terminal（終端）中手動執行 CMake 命令：
    1 cd C:\Users\你的用戶名\Projects\OpenCV_VSCode_CPP 2 mkdir build 3 cd build 4 cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Debug .. 5 nmake
  - 上述命令會在 build\ 下生成 OpenCV_VSCode_CPP.exe。
運行與調試
- Professional 版：
  - 在 CMake 構建完成後，PyCharm 會自動發現可執行文件（.exe）並在 “Run” 配置中列出。
  - 點擊項目右上方的運行配置下拉框，選擇 OpenCV_VSCode_CPP.exe，然後點擊綠色 ▶，即可運行。
  - 若要調試，點擊 “Debug” 小蟲子圖標，PyCharm 會以 Debug 模式啟動。
- Community 版：
  - 由於 Community 版不支持 C++ 調試器，你可以在 Terminal 中手動執行：
    1 cd C:\Users\你的用戶名\Projects\OpenCV_VSCode_CPP\build 2 OpenCV_VSCode_CPP.exe
    若要調試，只能在使用 Visual Studio Developer Command Prompt 下調用 Debug 版本，或使用其他外部調試器（如 WinDbg），這里不做詳細介紹。
示例驗證
- 運行後，你應當會如同在 VSCode 中一樣，看到彈出的圖像窗口：彩色原圖與灰度圖，並在控制台輸出 “按任意鍵退出…”。
- 確認無錯誤，即表示 C++ + OpenCV 已在 PyCharm 環境下調通（以 Professional 版為例）。

5.3 在 PyCharm 中運行與調試 C++ 示例#

PyCharm 版本	操作方式
Professional	1. 點擊右上角 Run/Debug 配置，選擇 `OpenCV_VSCode_CPP.exe` 2. 點擊 ▶ 執行，或點擊 🐞 進行調試。
Community	1. 在左側項目窗口，右鍵點擊項目根目錄 → “Open in Terminal”。 2. 在終端輸入： `cd build` `OpenCV_VSCode_CPP.exe` 若需調試，僅能外部工具）

小貼士：

如果你 Community 版想借助 GUI 形式編譯與調試 C++，請使用 CLion 或 VSCode。PyCharm Community 更適合作為文本編輯器與 Python IDE。

PyCharm Professional 可將 CMake 構建過程無縫納入 IDE，但若需調試核心斷點，確保 launch.json / Debug 配置正確指向生成的可執行文件。

常見問題與解決方案#

報錯 “import cv2: No module named cv2”
- 原因：Python 環境中沒有安裝 OpenCV-Python，或 VSCode/PyCharm 中選擇的解釋器並非預期的虛擬環境。
- 解決：
  1. 確認當前終端是否激活虛擬環境 ((venv) 前綴)。
  2. 在激活後執行 pip install opencv-python。
  3. 在 VSCode 中，點擊右下角 Python 版本號，確保選擇的解釋器路徑指向虛擬環境。
  4. 在 PyCharm Settings→Project Interpreter 中確認已安裝 opencv-python。
C++ 編譯報錯 “cannot open source file ‘opencv2/opencv.hpp’”
- 原因：includePath 中沒有正確包含 OpenCV include 目錄，或者 find_package(OpenCV) 失敗。
- 解決：
  1. 檢查系統環境變量 OPENCV_DIR 是否正確指向 ...\opencv\build\x64\vc15。
  2. 在 CMakeLists.txt 中打印 ${OpenCV_INCLUDE_DIRS}，確認 CMake 找到的路徑正確。
  3. 如果手動 cl 編譯，在 tasks.json 或命令行也要加上 /I "C:/opencv/opencv-4.8.0/build/include"。
運行時報錯找不到 opencv_worldXXX.dll
- 原因：系統 PATH 中沒有包含 OpenCV 的 bin 目錄，或者尚未重啟終端/IDE。
- 解決：
  1. 確認系統環境變量 Path 中已加入 C:\opencv\opencv-4.8.0\build\x64\vc15\bin。
  2. 重啟 VSCode、PyCharm 或者操作系統，然後重新運行。
  3. 如果問題依舊，可手動複製 opencv_world480.dll 到可執行文件算法目錄（僅作臨時測試）。
PyCharm CMake 加載失敗 / 無法檢測編譯器
- 原因：PyCharm Professional 未正確識別系統中的 CMake 或 MSVC。
- 解決：
  1. 在命令行中執行 cmake --version、cl，確認這兩個命令可用。
  2. 在 PyCharm Settings → Build, Execution, Deployment → CMake 中，手動指定 CMake 可執行文件完整路徑。
  3. 在 “CMake Profiles” 中，檢查 “Generator” 是否與實際安裝的工具鏈匹配（例如 MSVC 對應 “Visual Studio 17 2022” 或 “NMake Makefiles”）。
VSCode Python 調試無法彈窗顯示 cv2.imshow
- 原因：部分遠程/WSL 環境不支持 GUI 彈窗，或者 Python 解釋器選擇不正確。
- 解決：
  1. 確認使用的是本地 Windows 環境，而非 WSL/Remote SSH。
  2. 檢查 Python 解釋器是否為正確的虛擬環境。
  3. 在 VSCode 的 launch.json 中，console 字段改為 "externalTerminal", 確保彈窗可見。
編譯速度很慢 / 內存消耗大
- 原因：CMake 默認會同時生成 Debug/Release 多種版本，或者沒有用到增量編譯。
- 解決：
  1. 在 CMakeLists.txt 中指定：
    1 set(CMAKE_BUILD_TYPE Release)
  2. 如果使用 VSCode CMake Tools，切換到單一構建配置（右下角切換 “Debug” 或 “Release”）。
  3. 確保不要在同一個目錄里反覆 rm -rf build/* 再完整重建，而是只在必要時清理。

附錄#

7.1 Windows 環境變量簡要說明#

系統變量 vs 用戶變量：
- “系統變量”對所有用戶生效；“用戶變量”僅對當前 Windows 登錄用戶生效。
- 建議將 OPENCV_DIR、Path 中添加 OpenCV 路徑放入 系統變量，以保證 VSCode/其他工具都能識別。

常用變量：

變量名	建議值	作用
OPENCV_DIR	`C:\opencv\opencv-4.8.0\build\x64\vc15`	給 CMake `find_package(OpenCV)` 提供路徑
Path	`C:\opencv\opencv-4.8.0\build\x64\vc15\bin`	讓系統能找到 `opencv_world480.dll` 及其他 `.dll`
CMAKE_PREFIX_PATH	（可選）`C:\opencv\opencv-4.8.0\build`	讓某些 CMake 工具鏈搜索 OpenCV 時更快捷

7.2 CMakeLists.txt 詳細示例#

如果你想更深入地了解 CMakeLists.txt，下面給出一個更“健壯”的示例，支持 Debug/Release 雙配置，並自動設置安裝路徑：

1
cmake_minimum_required(VERSION 3.10)
2
project(OpenCV_VSCode_CPP)
3

4
# 設置 C++ 標準
5
set(CMAKE_CXX_STANDARD 17)
6
set(CMAKE_CXX_STANDARD_REQUIRED ON)
7

8
# 防止 Reconfig 時覆蓋舊的 Release/Debug 結果
9
if (NOT CMAKE_BUILD_TYPE)
10
  set(CMAKE_BUILD_TYPE Release CACHE STRING "Choose the type of build." FORCE)
11
endif()
12

13
# 查找 OpenCV
14
find_package(OpenCV REQUIRED)
15

16
# 打印信息
17
message(STATUS "==== OpenCV 信息 ====")
18
message(STATUS "OpenCV 版本： ${OpenCV_VERSION}")
19
message(STATUS "OpenCV 包路徑： ${OpenCV_DIR}")
20
message(STATUS "OpenCV 頭文件目錄： ${OpenCV_INCLUDE_DIRS}")
21
message(STATUS "OpenCV 庫文件： ${OpenCV_LIBS}")
22
message(STATUS "====================")
23

24
# 指定可執行文件輸出目錄
25
set(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/bin)
26

27
# 指定庫文件輸出目錄
28
set(LIBRARY_OUTPUT_PATH ${PROJECT_BINARY_DIR}/lib)
29

30
# 包含子目錄（如果你有其他子模塊可以分開管理）
31
# add_subdirectory(src)
32

33
# 添加主程序
34
add_executable(${PROJECT_NAME} src/main.cpp)
35

36
# 鏈接 OpenCV
37
target_link_libraries(${PROJECT_NAME} PRIVATE ${OpenCV_LIBS})
38

39
# 若需安裝
40
install(TARGETS ${PROJECT_NAME} RUNTIME DESTINATION bin)

解釋：

CMAKE_BUILD_TYPE 通過緩存變量管理了 Debug/Release，可在 CMake GUI 或命令行中指定 -DCMAKE_BUILD_TYPE=Debug，否則默認 Release。

將可執行文件輸出到 build/bin，使項目結構更清晰。

install(...) 方便以後打包安裝。

7.3 快速回顧#

Python + VSCode
1. 安裝 Python 並創建虛擬環境；
2. 安裝 VSCode Python 擴展；
3. pip install opencv-python opencv-contrib-python；
4. 編寫 opencv_test.py，執行並驗證 cv2.imshow 彈窗。
C++ + VSCode
1. 安裝 Visual Studio Build Tools（MSVC）+ CMake；
2. 下載並解壓 OpenCV Windows 預編譯包，配置環境變量 OPENCV_DIR 與 Path；
3. 安裝 VSCode C/C++、CMake Tools 擴展；
4. 創建含 CMakeLists.txt 和 src/main.cpp 的項目；
5. 在 VSCode 中執行 “CMake: Configure” → “CMake: Build”；
6. 調試（F5）或運行可執行文件，觀察圖像輸出。
Python + PyCharm
1. 安裝 PyCharm，新建項目並選擇虛擬環境；
2. 在 Project Interpreter 中安裝 opencv-python；
3. 編寫並運行 opencv_test.py，檢查圖像顯示。
C++ + PyCharm
1. PyCharm Professional：直接加載 CMake 項目，點擊 Build & Run；
2. PyCharm Community：在內置終端中手動執行 CMake + nmake；
3. 使用外部終端或調試器查看運行結果。

至此，你已經掌握了在 VSCode 與 PyCharm 兩大 IDE 下，如何同時配置並運行 OpenCV 的 Python 與 C++ 環境。祝你學習順利，愉快地開始你的計算機視覺之旅！