最常见原因是头文件实际不存在或路径配置错误；应先用find或文件管理器确认xxx.h是否存在于项目目录、第三方库目录或系统路径中，再核对#include写法（"xxx.h" vs ）、编译器搜索路径（g++ -v）及CMake target_include_directories等配置。
确认头文件是否真的存在
编译器报 No such file or directory，最常见原因是路径写错或文件压根没放对地方。先别急着改 -I 参数，直接用 find 或文件管理器查一遍：xxx.h 到底在不在你的项目目录、第三方库目录或系统路径里。
- 如果是自己写的头文件（比如
utils.h），检查它是否和源文件在同一目录，或子目录（如include/utils.h） - 如果是第三方库（如
json.hpp），确认你下载的是单头文件版本，且路径已正确解压；不是只复制了README.md就以为齐活了 - 用
ls -l include/xxx.h或dir include\xxx.h验证大小写——Linux/macOS 下XXX.h和xxx.h是两个文件
检查 #include 写法与搜索路径是否匹配
#include "xxx.h" 和 #include 的查找逻辑完全不同：前者优先从当前源文件所在目录开始找，后者跳过当前目录，直奔 -I 指定路径和系统默认路径。很多问题就卡在这儿。
- 自己写的头文件一律用双引号：
#include "config.h"，别图省事写成 - 用
g++ -v main.cpp（加-v不编译，只打印搜索路径）看编译器实际搜了哪些目录；注意输出里search starts here:后面的顺序 - 如果头文件在
./deps/libuv/include/，要加-I deps/libuv/include，而不是-I deps/libuv——后者会让编译器去找deps/libuv/xxx.h，而非deps/libuv/include/xxx.h
第三方库没装全或环境变量干扰
某些库（如 OpenCV、Boost）安装后头文件分散在不同子目录，或依赖 pkg-config 输出路径。单纯 apt install libopencv-dev 可能不够，还得确认开发包是否真包含头文件。
- 运行
dpkg -L libopencv-dev | grep "\.h$"（Debian/Ubuntu）或rpm -ql opencv-devel | grep '\.h$'（RHEL/CentOS）验证头文件是否存在 - 如果用了 conda 或 vcpkg，确保 shell 当前激活了对应环境，且没被系统级
CPATH或CPLUS_INCLUDE_PATH覆盖——这两个环境变量会无条件插入到搜索路径最前面，容易导致“明明有却找不到” - Mac 上用 Homebrew 装的库（如
jsoncpp），头文件常在/opt/homebrew/include/jsoncpp/，需显式加-I /opt/home/homebrew/include，不能只信pkg-config --cflags jsoncpp的输出（有时漏路径）
CMake 项目里 target_include_directories 配置错误
CMake 不是自动把所有子目录都加进头文件搜索路径的。即使 add_subdirectory() 引入了第三方库，也不代表它的头文件路径会透传给你的 target。
- 必须显式调用
target_include_directories(your_target PRIVATE ${JSONCPP_INCLUDE_DIRS})，而不是只写find_package(jsoncpp) -
PRIVATE表示仅本 target 可用；若其他 target 也要包含这个头文件，得用INTERFACE或PUBLIC，否则链接时可能报错 - 避免在
CMakeLists.txt里写include_directories(...)全局设置——它不区分 target，容易污染构建，且 CMake 3.0+ 已不推荐
C++ 头文件路径问题本质是“编译器看到的路径”和“你认为它该看到的路径”不一致。调试时优先用 g++ -v 或 clang++ -v 看真实搜索行为，比盲目加 -I 更可靠。尤其要注意双引号 vs 尖括号、CMake target 粒度、以及环境变量的隐式覆盖——这三处最容易反复踩坑。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
