cmake 3.16+ 才可靠支持 target_precompile_headers，此前版本在 msvc 下可能生成但不使用，clang/gcc 常报错或静默失效；官方直至 3.16 才将其转为正式功能，并修复多配置生成器下的路径与作用域问题。
为什么 target_precompile_headers 在 CMake 3.16+ 才可靠
低于 3.16 的 CMake 版本对预编译头（PCH）支持极不稳定：MSVC 下可能生成但不被实际使用，Clang/GCC 则常报 Unknown CMake command "target_precompile_headers" 或静默失效。CMake 官方直到 3.16 才将该命令从实验性转为正式支持，且后续版本修复了多配置生成器（如 Visual Studio）下 PCH 路径解析错误、PRIVATE/PUBLIC 作用域传递失效等问题。
如果你用的是 CMake 3.15 或更早——别折腾 target_precompile_headers，要么升级 CMake，要么手动调用编译器生成 PCH（比如用 add_custom_command + add_custom_target），但维护成本高、跨平台难。
target_precompile_headers 的三种写法和适用场景
核心是控制头文件的“可见范围”和“是否强制包含”，不是所有写法都等效：
-
target_precompile_headers(mylib PRIVATE "pch.h")：只对mylib自身源文件生效，且不会自动#include "pch.h"—— 你得在每个.cpp文件顶部手动加#include "pch.h"（MSVC 要求严格顺序） -
target_precompile_headers(mylib PUBLIC "pch.h")：对mylib及所有链接它的 target 生效，但仅当它们也显式启用 PCH 时才起作用；不推荐，容易引发依赖混乱 -
target_precompile_headers(mylib INTERFACE "pch.h")：只影响链接者，自身不编译 PCH —— 这种写法基本没意义，别用
最常用、最安全的是第一种：PRIVATE + 手动 #include。它明确边界，避免头污染，也兼容 MSVC 的“必须首行包含”规则。
MSVC 下 stdafx.h 和 pch.h 的命名陷阱
MSVC 默认期望预编译头文件叫 stdafx.h（尤其在旧项目或 Visual Studio GUI 创建的项目里），但 CMake 并不强制这个名称。问题在于：如果 CMake 指定 pch.h，而你的源文件却写了 #include "stdafx.h"，编译会失败；反之亦然。
解决办法只有一个：保持名称统一。建议放弃 stdafx.h，全部用 pch.h，并在 CMake 中明确指定：
CMake 4.3.2 Windows x86_64 历史版本安装包，适合旧项目兼容、构建环境回退、CMakeLists.txt 迁移验证、Visual Studio/Ninja/Makefile 生成器测试和 C/C++ 项目维护。
target_precompile_headers(myapp PRIVATE "pch.h")
然后确保所有 .cpp 文件第一行是：
#include "pch.h"
另外注意：MSVC 要求 PCH 对应的实现文件（如 pch.cpp）必须用 /Yc"pch.h" 编译，而其他文件用 /Yu"pch.h"。CMake 会自动处理这点，但前提是 pch.cpp 必须加入 target 源文件列表，且不能被排除（比如没加进 add_executable 的 SOURCES 里）。
Clang/GCC 开启 PCH 需要额外开关
Clang 和 GCC 默认不启用 PCH，即使你写了 target_precompile_headers，它们也只会跳过该指令（无报错）。必须显式开启：
- Clang：加
-Xclang -emit-pch（生成）和-Xclang -include-pch（使用），但 CMake 不直接暴露这些。正确做法是设置COMPILE_OPTIONS：
set_property(TARGET myapp PROPERTY CXX_PRECOMPILE_HEADERS ON)
这行必须放在 target_precompile_headers 之前，否则 Clang/GCC 无视。
- GCC 4.9+ 支持
-Winvalid-pch检查 PCH 有效性，建议加上以避免缓存脏数据导致的诡异编译失败 - Clang 的 PCH 是模块化的，路径敏感；若
pch.h包含相对路径头（如"../common/config.h"），生成的 PCH 可能无法被其他目录下的源文件复用
跨平台项目务必测试 Clang/GCC 下 PCH 是否真被加载：编译时加 --verbose，看命令行里有没有 -include-pch 或 -include 对应的 .gch/.pch 文件。
真正麻烦的从来不是写对那几行 CMake，而是确认 PCH 被编译器实际消费了——尤其在 CI 环境里，缓存、路径、生成器差异会让它悄无声息地失效。每次改完 PCH 配置，至少跑一次 clean build 并检查编译日志里的预编译头路径。
