这是一个可直接复制的 OpenCV 工程模板（VS2022 + CMake + Ninja）。模板的作用：新建 OpenCV 项目时不用每次手动加 include/lib 路径——复制模板、改项目名、加源文件即可。整套约定是：CMake 为唯一构建系统、依赖走环境变量 + find_package、构建输出在 out/build/、不写死路径。

前置环境变量：

  • OpenCV_DIR = <OpenCV安装目录>\build\x64\vc16\lib
  • PATH 追加：<OpenCV安装目录>\build\x64\vc16\bin

一、目录结构

<项目根目录>\OpenCVTemplate\
├── CMakeLists.txt
├── CMakePresets.json
├── .gitignore
├── src\
│   └── main.cpp
└── out\
    └── build\

二、CMakeLists.txt（复制到项目根目录）

cmake_minimum_required(VERSION 3.20)
project(OpenCVTemplate LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# ---------- OpenCV ----------
# OpenCV_DIR 由 CMakePresets.json 从环境变量注入，这里不写路径
find_package(OpenCV REQUIRED)

# ---------- 源文件 ----------
set(SOURCES
    src/main.cpp
)

add_executable(${PROJECT_NAME} ${SOURCES})

target_include_directories(${PROJECT_NAME} PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/src
    ${OpenCV_INCLUDE_DIRS}
)

target_link_libraries(${PROJECT_NAME} PRIVATE
    ${OpenCV_LIBS}
)

三、CMakePresets.json（复制到项目根目录）

{
  "version": 3,
  "configurePresets": [
    {
      "name": "debug",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/out/build/${presetName}",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "OpenCV_DIR": "$env{OpenCV_DIR}"
      }
    },
    {
      "name": "release",
      "inherits": "debug",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ],
  "buildPresets": [
    { "name": "debug", "configurePreset": "debug" },
    { "name": "release", "configurePreset": "release" }
  ]
}

版本待核实：预设文件 "version": 3 与 CMakeLists.txt 里 cmake_minimum_required(VERSION 3.20) 的版本要求是否匹配（version 3 预设需较新的 CMake），首次配置前请确认本机 / VS2022 自带 CMake 的实际版本。

四、.gitignore（复制到项目根目录）

.vs/
out/
CMakeUserPresets.json
*.user
*.suo
*.pdb
*.ilk

五、src/main.cpp（自检代码，可整段复制）

#include <opencv2/opencv.hpp>
#include <iostream>

int main()
{
    std::cout << "OpenCV 版本: " << CV_VERSION << std::endl;

    // 生成一张 640x480 的渐变测试图并保存
    cv::Mat img(480, 640, CV_8UC3);
    for (int y = 0; y < img.rows; ++y)
        for (int x = 0; x < img.cols; ++x)
            img.at<cv::Vec3b>(y, x) = cv::Vec3b(
                static_cast<uchar>(x * 255 / img.cols),
                static_cast<uchar>(y * 255 / img.rows),
                128);

    const std::string out = "test_output.png";
    if (cv::imwrite(out, img))
        std::cout << "测试图已保存: " << out << std::endl;
    else
    {
        std::cerr << "保存失败!" << std::endl;
        return 1;
    }
    return 0;
}

六、VS2022 使用步骤

步骤操作
1建目录 <项目根目录>\OpenCVTemplate，放入上面 4 个文件
2确认环境变量 OpenCV_DIR 已设、PATH 已加 OpenCV bin（没配先按环境变量方案配好）
3VS2022 → 文件 → 打开 → 文件夹 → 选项目根目录
4底部状态栏配置选择器选 debug（或 release）
5顶部启动项选 OpenCVTemplate.exe，F5 构建运行

验证： 控制台打印 OpenCV 版本号；out\build\debug\ 下生成 test_output.png，打开是红绿蓝渐变图。

七、常见问题

问题原因解决
Could not find OpenCVConfig.cmakeOpenCV_DIR 没生效或值不对确认它指向 ...\vc16\lib（该目录含 OpenCVConfig.cmake），改完重启 VS
运行时报找不到 opencv_world4100d.dllPATH 没加 OpenCV bin确认 PATH 含 <OpenCV安装目录>\build\x64\vc16\bin，改完重启 VS
链接报错找不到 .libDebug/Release 库文件不匹配Debug 用 opencv_world4100d.lib，Release 用 opencv_world4100.lib，确认 lib 目录里都在
LNK2038 运行时库冲突项目 /MT 而 OpenCV 是 /MD 构建保持 MSVC 默认 /MD，不要手动改运行时库

八、如何复用到新项目

  1. 整个目录复制一份，改名（纯英文路径，无空格、无 ++）。
  2. 改 CMakeLists.txt 里的 project(OpenCVTemplate ...) 为新项目名。
  3. 在 SOURCES 里增删源文件。
  4. OpenCV_DIR 与 PATH 是机器级配置，模板本身不绑定具体路径，换机器只需重设环境变量。