Core Guidelines 本身不解决跨平台工程一致性问题，真正落地依赖构建系统、CI配置、头文件组织和编译器标志的统一约束；需用CMake统一控制C++标准、禁用扩展、规范包含路径、规避std::filesystem兼容性陷阱，并确保静态分析与目标平台编译环境严格对齐。
Core Guidelines 本身不解决跨平台工程一致性问题，它只提供编码风格和安全实践建议；真正落地靠的是构建系统、CI 配置、头文件组织和编译器标志的统一约束。
用 CMake 统一管理编译器行为，而非依赖 IDE 默认设置
Windows（MSVC）、Linux（GCC/Clang）、macOS（Clang）对标准支持、警告级别、ABI 的默认处理差异极大。不显式控制 CMAKE_CXX_STANDARD、CMAKE_CXX_EXTENSIONS 和 compiler flags，std::optional 或 [[nodiscard]] 就可能在某个平台静默降级或报错。
- 强制设为
CMAKE_CXX_STANDARD 17（或 20），并关闭扩展：CMAKE_CXX_EXTENSIONS OFF - 全局启用 Core Guidelines 检查项：GCC/Clang 加
-Wno-unused-parameter -Wno-missing-field-initializers（避免与gsl::not_null冲突），MSVC 加/wd4100 /wd4350 - 禁用平台特有宏污染：Linux/macOS 上定义
_GNU_SOURCE或_DARWIN_C_SOURCE前，先检查是否已由 CMake 自动注入
头文件路径与模块边界必须与 OS 路径分隔符解耦
#include "utils/string_view.h" 在 Windows 下若被写成 #include "utils\string_view.h"，Clang 和 GCC 会直接报错；而 MSVC 对反斜杠容忍度高，导致“本地能编”但 CI 失败。
- 所有
#include使用正斜杠/，CMake 中也统一用target_include_directories(... PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include) - 禁止在源码中硬编码
\\或调用std::filesystem::path拼接头文件路径（预处理器不识别） - 模块化时慎用
export：Clang 16+ 支持模块映射，但 MSVC 模块仍要求.ixx后缀且不兼容 GCC，现阶段建议全项目禁用模块，回归 header-only + CMake interface library
std::filesystem 在 macOS 和旧 Linux 发行版上不可靠
Core Guidelines 推荐用 std::filesystem 替代 C 风格路径操作，但它在 macOS 10.15+ 才完整支持 std::filesystem::canonical，CentOS 7 的 libstdc++ 甚至没有实现 std::filesystem::exists（链接时报 undefined reference）。
立即学习“C++免费学习笔记（深入）”；
- 检查编译器 + 标准库组合：Clang + libc++ 在 macOS 安全；GCC 9+ + libstdc++ 6.0.28+ 在 Ubuntu 20.04+ 可用；其余情况回退到
boost::filesystem或封装 POSIXstat()/realpath() - 不要在
constexpr上下文中使用std::filesystem::path（非字面量类型） - CI 中必须覆盖最低目标系统：例如 macOS 12、Ubuntu 18.04、Windows Server 2019，不能只测最新版
静态分析工具链必须与平台构建命令对齐
用 VS Code 插件跑 clang-tidy 检查 Windows 代码，但没传 -D_WIN32 和 MSVC 的 __declspec(dllexport) 宏，会导致误报“未声明的符号”；同理，Linux 上用 cppcheck 不加 --platform=unix64，size_t 位宽判断就出错。
- CI 中每个平台使用该平台原生编译器运行
clang-tidy：Linux/macOS 用 Clang，Windows 用clang-cl并配--extra-arg="--driver-mode=cl" - 配置
.clang-tidy时，用-checks="-*,cppcoreguidelines-*"显式启用，避免因版本升级默认关闭某些项 - 把
clang-tidy结果转成 SARIF 并上传到 GitHub Code Scanning，确保三端报告格式一致，而不是各自解析文本输出
最常被忽略的一点：Core Guidelines 的 gsl::span 和 gsl::not_null 在 Windows 上需链接 gsl-lite 的静态库，但 Linux/macOS 通常 header-only 即可；如果 CMake 没区分 target_link_libraries(core PRIVATE gsl::gsl) 和 target_link_libraries(core PRIVATE gsl-lite)，链接阶段就会失败——这问题不会在语法检查或单元测试里暴露，只在最终打包时浮现。
