C++跨平台项目规范：Core Guidelines在Windows/Linux/macOS统一落地【工程一致性】

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 "utilsstring_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 或封装 POSIX stat()/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)，链接阶段就会失败——这问题不会在语法检查或单元测试里暴露，只在最终打包时浮现。