VS编译器仅搜索项目属性中“附加包含目录”指定的路径，不自动递归子目录或包含源文件所在目录；双引号优先查当前目录，尖括号跳过当前目录直接查附加目录和系统路径。
确认 #include 路径是否被编译器实际搜索到
VS 默认只搜索项目属性里 附加包含目录（Configuration Properties → C/C++ → General → Additional Include Directories）列出的路径，不会自动递归扫描子目录，也不会默认包含源文件所在目录（除非显式写 ./ 或 $(ProjectDir)）。
常见错误现象：#include "utils.h" 在 src/core/ 下能编译，但移到 test/ 目录后报 C1083；或 #include <json.hpp> 报错，但文件明明在 third_party/nlohmann/ 里。
- 用
/showIncludes编译开关查看实际搜索路径：在项目属性 →C/C++ → Command Line → Additional Options中添加/showIncludes，重新编译，输出里每行Note: including file:后面的路径就是被成功找到的头文件路径 - 相对路径必须相对于「当前翻译单元」（即
.cpp文件）所在目录，不是工程根目录，也不是构建目录 - 绝对路径尽量避免硬编码（如
#include "C:\dev\lib\header.h"），会导致协作和 CI 失败；改用环境变量（如$(MYLIB_DIR)\header.h）并在项目中定义该变量
"quotes" 和 <angle brackets> 的搜索行为差异
这是最容易被忽略的底层机制：双引号形式优先在当前源文件目录及其父目录中查找，再 fallback 到 Additional Include Directories；尖括号形式则跳过当前目录，直接从 Additional Include Directories 和系统路径（如 Windows Kits）开始搜索。
- 本地头文件（如
"config.h"、"../common/log.h"）务必用双引号，否则可能意外命中系统同名头文件（比如误包含<memory.h>而非你自己的"memory.h"） - 第三方库头文件（如
<nlohmann/json.hpp>、<boost/filesystem.hpp>）建议用尖括号，并确保其根路径（如nlohmann/所在目录）已加入Additional Include Directories，而非写成"nlohmann/json.hpp" - VS 不支持
#include "subdir/../header.h"这类含..的路径在双引号中做运行时解析——它只是字符串，最终仍按字面路径拼接后查找
检查路径中的空格、大小写与特殊字符
Windows 文件系统不区分大小写，但 MSVC 编译器在解析 #include 字符串时是**逐字匹配**的，且对空格极其敏感。路径中出现中文、括号、空格或 Unicode 字符，极易导致 C1083。
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
立即学习“C++免费学习笔记（深入）”；
- 若包含目录路径含空格（如
C:\Program Files\MyLib\include），必须用双引号包裹整个路径：在项目属性中填"C:\Program Files\MyLib\include"，否则 VS 会截断为C:\Program - 检查文件扩展名是否拼错：
#include "Utils.H"在 Windows 下可能成功，但在 CI 的 Linux 构建机上必然失败；统一用小写.h或.hpp - Git for Windows 默认禁用大小写敏感，可能导致
Header.h和header.h共存而不报错，但换到原生 Linux 环境就出问题
预处理器输出验证真实包含路径
当路径看似正确却仍报错时，最可靠的方式是让编译器“说出它看到的路径”——生成预处理后的文件，看 #include 行是否被展开或替换。
- 右键 .cpp 文件 →
Properties → C/C++ → Preprocessor → Generate Preprocessed File = Yes (/P)，编译后会在输出目录生成xxx.i文件 - 打开该
.i文件，搜索#line指令或原始#include行，确认路径字符串是否被宏展开、是否含不可见字符（如 BOM、全角引号） - 若发现路径变成
#include "D:\proj\src\..\inc\log.h"，说明相对路径计算未被简化，而目标文件实际在D:\proj\inc\log.h—— 此时应改用#include "inc/log.h"并把D:\proj加入包含目录
路径问题本质是编译器与文件系统之间的契约匹配，不是语法错误，所以 IDE 的智能提示常失效；必须依赖 /showIncludes 或 /P 这类底层开关来暴露真实行为。
