新手必备：VSCode及PyCharm配置OpenCV全方位指南（含Python与C++）

新手入门：VSCode与PyCharm配置OpenCV的全面指引（涵盖Python与C++）

适用对象 ：刚接触编程的人，希望在VSCode和PyCharm这两款常用集成开发环境中，学会配置并使用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++示例程序。能快速实现图像读取、灰度转换、窗口显示等基础操作，为后续计算机视觉开发筑牢基础。

---

目录

1. 环境准备
   1.1. 系统要求
   1.2. 工具下载与安装概述

2. Python + VSCode环境配置
   2.1. 安装Python
   2.2. 创建并激活虚拟环境
   2.3. 安装VSCode及Python插件
   2.4. 安装OpenCV（Python版）
   2.5. 在VSCode中创建与配置项目
   2.6. 编写并运行Python示例脚本

3. 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++示例程序

4. Python + PyCharm环境配置
   4.1. 安装PyCharm
   4.2. 创建Python项目并选择解释器
   4.3. 在PyCharm中安装OpenCV（Python版）
   4.4. 编写与运行Python示例脚本

5. C++ + PyCharm环境配置
   5.1. PyCharm对C++的支持说明
   5.2. 借助CMake构建C++项目并使用终端/外部工具
   5.3. 在PyCharm中运行与调试C++示例

6. 常见问题与解决办法

7. 附录
   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	提供Python运行时，执行OpenCV Python示例	https://www.python.org/downloads/
Visual Studio Build Tools	提供Windows下C++编译器（MSVC）、CMake等构建工具
https://visualstudio.microsoft.com/zh-hans/downloads/ (选择“Build Tools for
Visual Studio 2022”)
VSCode	微软出品的轻量级跨平台IDE，适合Python & C++开发	https://code.visualstudio.com/
PyCharm	JetBrains出品的Python IDE	https://www.jetbrains.com/pycharm/
OpenCV预编译包	提供C++版库文件（Windows下为.exe或.zip）
https://opencv.org/releases/

安装顺序建议 ：

1. 安装Python，勾选“Add Python 3.x to PATH”（方便后续在终端直接使用python命令）。
2. 安装Visual Studio Build Tools，并在安装过程中勾选“C++ build tools”与“Windows 10/11 SDK”。
3. 安装VSCode与PyCharm。
4. 下载并解压OpenCV预编译包。
5. 按照后续章节的步骤，分别配置Python和C++环境。

---

Python + VSCode环境配置

本节将带你从零开始，在Windows平台上搭建基于VSCode的Python + OpenCV开发环境，并运行一个简单图像读取与显示示例。

2.1 安装Python

1. 下载Python安装包

   • 访问 Python官网，点击最新3.x版本（例如Python 3.11.x）的Windows Installer（根据自己系统选择64-bit）。

   • 运行安装程序

   • 勾选页面底部的 “Add Python 3.x to PATH” ，然后点击 “Install Now” 。

   • 等待安装完成。

   • 验证安装

   • 打开 命令提示符 (CMD) 或 PowerShell ，输入：

     python –version

若显示类似Python 3.11.x，说明安装成功。

 * 同时也可以验证`pip`：

       pip --version

若显示pip 23.x.x from ...，表示pip可用。

2.2 创建并激活虚拟环境

为了保证项目依赖独立，建议使用虚拟环境（venv）。

1. 打开 命令提示符 (CMD) 或 PowerShell ，进入你希望存放项目的文件夹，例如：

    cd C:\Users\你的用户名\Projects
    mkdir OpenCV_VSCode_Python
    cd OpenCV_VSCode_Python
   

2. 创建虚拟环境：

    python -m venv venv
   

这会在当前文件夹下创建一个名为venv的子文件夹，里面包括独立的Python解释器。

1. 激活虚拟环境：

   • 在 命令提示符 ：

     venv\Scripts\activate.bat

   • 在 PowerShell （可能需要先解除脚本执行限制）：

     Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
     .\venv\Scripts\Activate.ps1

   • 激活后，终端提示符会出现前缀(venv)。

注意 ：后续所有在终端执行的pip install、python命令，都将在该虚拟环境中生效。如需退出虚拟环境，输入deactivate即可。

2.3 安装VSCode及Python插件

1. 下载VSCode

   • 访问 VSCode官网，点击下载适用于Windows的安装程序。
   • 安装时勾选“Add to PATH”、“Register Code as Editor for supported file types”等选项（方便后续直接在资源管理器右键打开）。

   • 打开VSCode

   • 安装完成后，双击运行VSCode。

   • 安装Python插件

   • 在左侧扩展图标（Extensions）中，搜索“Python”，由Microsoft发布的官方扩展为：

     Python (ms-python.python)

   • 点击“Install”进行安装。

   • 安装完毕后，VSCode底部状态栏会出现已识别的Python解释器选项。

2.4 安装OpenCV（Python版）

1. 确保虚拟环境已激活

   • 如果之前已经退出，重新打开项目目录，在终端中重新激活：

     cd C:\Users\你的用户名\Projects\OpenCV_VSCode_Python
     venv\Scripts\activate.bat

2. 安装OpenCV-Python包

   • 在终端输入：

     pip install opencv-python opencv-contrib-python

   • 解释：

   • opencv-python：主模块，包含核心功能。

   • opencv-contrib-python：包含额外的算法模块（contrib），推荐同时安装。

   • 验证安装

   • 在终端启动Python交互：

     python

   • 在交互式命令行输入：

     import cv2
     print(cv2.version)

   • 如果输出类似4.8.0或者其他版本号，就说明安装成功。

   • 输入exit()退出Python交互。

2.5 在VSCode中创建、配置项目

1. 打开项目文件夹

   • 在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，输入：

     import cv2

     # 测试OpenCV是否可用
     img = cv2.imread(‘test.jpg’)
     cv2.imshow(‘Test Window’, img)
     cv2.waitKey(0)
     cv2.destroyAllWindows()

   • 如果import时没有红线报错，说明VSCode已经正确识别cv2模块。

注意 ：示例中使用cv2.imshow需要在Windows本地环境执行，且要确保当前目录下存在名为test.jpg的图像文件。可以自行下载一张测试图片命名为test.jpg放在项目根目录。

2.6 编写并运行Python示例脚本

1. 准备测试图像

   • 在项目根目录下，新建一个名为test.jpg的图像（任意一张照片即可）。

   • 完整示例代码 （opencv_test.py）：

     import cv2

     def main():
     # 读取本目录下的test.jpg
     img = cv2.imread(‘test.jpg’)
     if img is None:
     print(‘无法读取test.jpg，请确认文件存在于当前目录’)
     return

      # 将图像转换为灰度并显示
      gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
     
      cv2.imshow('原图', img)
      cv2.imshow('灰度图', gray)
     
      print('按任意键关闭窗口...')
      cv2.waitKey(0)
      cv2.destroyAllWindows()
     

     if name == ‘main‘:
     main()

2. 在VSCode中执行

   • 打开opencv_test.py，可以点击右上方的绿色运行按钮（▶），或者在终端中手动输入：

     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）

1. 下载

   • 访问 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空间与数分钟时间。

2. 验证

   • 安装完成后，打开x64 Native Tools Command Prompt for VS 2022（在「开始菜单 → Visual Studio 2022」中即可找到）。

   • 输入：

     cl

如果出现Microsoft (R) C/C++ Optimizing Compiler等输出，则说明MSVC已就绪。

 * 同时验证CMake：

       cmake --version

如果输出类似cmake version 3.27.x，说明CMake安装成功。

3.2 下载并配置OpenCV预编译包

1. 下载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

   • 右键“此电脑”→“属性”→“高级系统设置”→“环境变量(N)…”。

   • 在“系统变量(S)”区域，点击“新建(W)…”，变量名填OPENCV_DIR，变量值填：

       C:\opencv\opencv-4.8.0\build\x64\vc15   # 根据实际版本和文件夹填写，通常到build\x64\vc15
     

   • 点击确定。

   • 修改Path

   • 在“系统变量(S)”区域，找到Path，选中后点击“编辑(I)…”。

   • 添加一行：

       C:\opencv\opencv-4.8.0\build\x64\vc15\bin
     

   • 点击确定，保存退出。

   • 验证（在新的命令提示符中）

     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++扩展

1. 打开VSCode

   • 如果还未运行VSCode，请双击打开。

   • 安装C/C++扩展

   • 在左侧扩展市场 (Extensions) 中，搜索：

     C/C++

   • 由Microsoft发布的官方扩展“C/C++” (ms-vscode.cpptools) 位于搜索结果第一。

   • 点击“Install”进行安装。

2. 安装CMake Tools扩展（可选，但强烈推荐）

   • 在扩展市场搜索：

     CMake Tools

   • 由Microsoft发布的“CMake Tools” (ms-vscode.cmake-tools) 拓展可以让VSCode本身识别CMake项目、自动生成配置，便于日后管理复杂项目。

   • 点击“Install”安装。

**小贴士