VS Code使用CMake配置OpenCV时编译报错找不到opencv.hpp头文件

在VS Code中创建基于OpenCV的C++项目时，CMake配置环节无异常提示，但编译阶段无法识别引入的OpenCV头文件，触发编译错误。

问题复现代码 #

CMakeLists.txt 配置 #

cmake_minimum_required(VERSION 3.0.0)
project(ASCII VERSION 0.1.0)

include(CTest)
enable_testing()

find_package( OpenCV REQUIRED PATHS "C:/opencv")
include_directories(${OpenCV_INCLUDE_DIRS})
add_executable( ASCII main.cpp )
target_link_libraries( ASCII ${OpenCV_LIBS} )

set(CPACK_PROJECT_NAME ${PROJECT_NAME})
set(CPACK_PROJECT_VERSION ${PROJECT_VERSION})
include(CPack)

main.cpp 源码 #

#include <stdio.h>
#include <opencv2/opencv.hpp>

using namespace cv;
int main(int argc, char** argv )
{

    Mat image;
    image = imread("C:/Users/Vivek/lenna.png");
    if ( !image.data )
    {
        printf("No image data \n");
        return -1;
    }
    namedWindow("Display Image", WINDOW_AUTOSIZE );
    imshow("Display Image", image);
    waitKey(0);
    return 0;
}

编译报错输出 #

main.cpp(2): fatal error C1083: Cannot open include file: 'opencv2/opencv.hpp': No such file or directory

核心问题是find_package的搜索路径配置错误：

• Windows平台官方预编译的OpenCV安装包，根目录下分为sources（源码）和build（编译好的库文件、CMake配置文件）两个子目录，OpenCVConfig.cmake文件存放在build目录下，而非OpenCV根目录。
• 原配置中PATHS参数指向C:/opencv根目录，CMake无法匹配到正确的OpenCV配置文件，会导致${OpenCV_INCLUDE_DIRS}变量为空，include_directories命令实际没有添加任何头文件搜索路径，因此编译阶段找不到opencv2开头的头文件。
• 旧版本CMake的全局目录配置写法include_directories容易出现作用域异常，也会加剧这类路径不生效的问题。
• 之前生成的CMake缓存会保留错误的路径配置，修改配置后如果不清理缓存，新的配置不会生效。

按以下步骤调整即可解决问题：

• 修正find_package的搜索路径，将路径指向OpenCV的build目录（如果是自行编译的OpenCV，则指向编译输出的install目录），例如预编译包解压到C盘根目录时，路径应写为C:/opencv/build。
• 完全删除之前CMake生成的build缓存目录，避免旧的错误配置干扰新的配置流程。
• 替换老旧的全局头文件配置写法，改用target级别的头文件绑定，确保头文件路径只作用于当前项目目标，避免作用域异常。
• 配置CMake时选择和OpenCV版本匹配的编译架构（例如x64版本的OpenCV对应x64编译套件，不要选x86套件），避免架构不匹配导致的后续链接错误。

修复后的完整CMakeLists.txt参考如下：

cmake_minimum_required(VERSION 3.0.0)
project(ASCII VERSION 0.1.0)

include(CTest)
enable_testing()

# 注意将路径替换为自己本机OpenCV的build目录实际路径
find_package( OpenCV REQUIRED PATHS "C:/opencv/build")
add_executable( ASCII main.cpp )
# 替换全局include_directories为目标绑定的头文件配置
target_include_directories(ASCII PRIVATE ${OpenCV_INCLUDE_DIRS})
target_link_libraries( ASCII PRIVATE ${OpenCV_LIBS} )

set(CPACK_PROJECT_NAME ${PROJECT_NAME})
set(CPACK_PROJECT_VERSION ${PROJECT_VERSION})
include(CPack)

如果不确定路径是否配置正确，可以在find_package行下方添加一行调试代码：

message(STATUS "OpenCV头文件路径：${OpenCV_INCLUDE_DIRS}")

重新执行CMake配置时，如果输出的路径为空，说明搜索路径仍然错误，需要继续调整PATHS参数到存放OpenCVConfig.cmake的正确目录。

内容的提问来源于stack exchange，提问作者Vivek Kumar