写 Win32 程序超过三个月，大概率被这几条报错教育过：明明照 MSDN 抄下来的 API，编译时给你一个 C2065 'xxx': undeclared identifier；更狠的是预处理阶段直接甩一条 C1189 #error，提示你把 WINVER 或 _WIN32_WINNT 设对。这个"版本控制宏"，指的就是 WINVER、_WIN32_WINNT、NTDDI_VERSION、_WIN32_IE 这一组预处理器宏，专门控制 Windows SDK 头文件里哪些声明对当前项目可见。这篇文章把它们的来龙去脉、取值关系、配置方法和排查经验一次讲透，适合刚上手 Win32 的初学者，也适合被版本宏折磨过的老开发——尤其是那种"换台机器编译就玄学报错"的项目。
1. 版本控制宏到底在管什么
1.1 一套头文件，服务二十多年的 API
Windows SDK 的头文件家族（winbase.h、winuser.h、shellapi.h 这些）要同时声明从 Windows 2000 到 Windows 11 的几千个 API。不可能每一个大版本都 fork 一套全新头文件，更不可能把所有 API 无条件全部摆出来——旧项目的重定义错误会多到没法看。所以微软的策略是：同一个头文件，靠#if、#elif预处理指令包出好几层，哪一层展开，取决于你在 include 之前定义的版本宏。版本宏就像一扇门上的多把钥匙，你用哪把钥匙，门就开放到哪一层。
这个设计有个直接后果：同样一份 main.cpp，设成 0x0501 编译出来的 API 可见面很"复古"，设成 0x0A00 就是最新一代。改动一行宏，等于换了一套"API 世界观"。
1.2 宏影响的远不止函数声明
很多人以为版本宏只管函数原型，实际上它管的范围要宽得多：
- 函数原型。比如 GetTickCount64、SetThreadDescription，门槛不够直接看不见。
- 结构体字段。Vista 才有的 STARTUPINFOEXW，以及它配套的 PROC_THREAD_ATTRIBUTE_* 常量，整体都包在版本判断里。宏不够高，类型都不存在，后面所有引用它的代码全部报错。
- 常量与标志位。像 PROCESS_QUERY_LIMITED_INFORMATION 这种 Vista 才引入的访问权限常量，在头文件里同样被版本宏包着。
- 库关联。
#pragma comment(lib, ...)有时也要看版本宏决定默认带哪个导入库，宏不一致时会莫名奇妙出现链接错误。
所以报错形式多种多样，根子往往都在同一个地方：你的目标版本声明低于代码里使用的 API 所需版本。
1.3 编译期契约和运行期检测是两码事
这里必须先把一个误区拆开。版本宏解决的是"编译时这个工程承认自己支持哪个最低系统"，它是契约，不是体检。你在代码里写if (IsWindows10OrGreater())然后调用 Win10 专属 API，这不会让编译器改变看法——宏没设对，该藏起来的声明照样藏。运行期检测解决的是"当前这台机器上能不能用某个新特性"，那是一个完全不同的问题，后面第 3 节会专门讲。
2. 四个核心宏的取值与换算关系
2.1 WINVER 与 _WIN32_WINNT：先从"谁在前"说起
WINVER 是资历最老的那个版本宏，早期 Windows 头文件判断版本基本靠它。后来微软统一推荐使用 _WIN32_WINNT，语义一样，取值也一样，只是命名更明确——它直接告诉你这是针对 32 位 Windows 版本号的门槛。现在多数项目两个都写，或者只写 _WIN32_WINNT、让 SDK 头文件顺手把 WINVER 补齐。我习惯两个都显式写，原因后面"坑"这一节会说。
取值本身都是十六进制的主次版本：0x0501 表示 XP，0x0600 表示 Vista，0x0601 表示 Win7，0x0602 表示 Win8，0x0603 表示 Win8.1，0x0A00 表示 Win10/Win11。Windows 10 开始主版本号直接跳到 10，所以是 0x0A00，这个别按十进制去理解，它不是一万人，就是十六进制的 10。
2.2 NTDDI_VERSION：把补丁级都算进去
NTDDI_VERSION 是这四个宏里粒度最细的。它不光管主次版本，还把服务包（SP）和功能更新的层级也编进数值里。格式上大致是"主版本、次版本、SP/构建层"压成一个 32 位整数：0x06010000 是 Win7，0x06020000 是 Win8，0x0A000000 是 Win10。早期你还会看到 0x05010200 这种——XP SP2 就是这样把 SP 号编进低位。
SDK 里给这些值起了别名，比较新的 SDK 从 NTDDI_WIN7、NTDDI_WIN8、NTDDI_WINBLUE（对应 8.1）、NTDDI_WIN10 一路排到 NTDDI_WIN11。Windows 11 的 _WIN32_WINNT 数值和 Windows 10 一样都是 0x0A00，但 NTDDI 这一层出现了 NTDDI_WIN11 之类的细分值（0x0A00000A 起步，不同功能更新还有更细的区分），用来在同一个"10"大版本下标记新功能。这个设计对只做桌面应用的人影响不大，但你的代码如果依赖 Windows 11 的某些特定更新，就得开始关注 NTDDI 这一层了。
2.3 _WIN32_IE：管的是界面控件这套
_WIN32_IE 是另一个维度，它控制 Common Controls（comctl32）和部分 Shell 相关头文件里能看到多新的界面特性。取值用的是 IE 版本号做锚点：0x0400 对应 IE 4.0，0x0500 对应 IE 5.0，0x0600 对应 IE 6.0，0x0800 对应 IE 8.0，0x0A00 对应 IE 11。这串值看着像浏览器历史，实际含义是"使用这一层公共控件的界面能力"。
很多现代界面代码需要设一个较新的 _WIN32_IE，否则连 ListView_SetView 这种站在 IE 5.01 门槛上的宏都看不见。它是四兄弟里最容易被漏掉的，但漏掉的结果往往不是报错，而是"控件行为悄悄变老"——最坑。
2.4 一张表把取值和换算说清
| 目标系统 | WINVER / _WIN32_WINNT | NTDDI_VERSION 别名（值） | _WIN32_IE 建议 |
|---|---|---|---|
| Windows 2000 | 0x0500 | NTDDI_WIN2K（0x05000000） | 0x0400 |
| Windows XP | 0x0501 | NTDDI_WINXP（0x05010000） | 0x0500 |
| Windows Server 2003 | 0x0502 | NTDDI_WS03（0x05020000） | 0x0500 |
| Windows Vista | 0x0600 | NTDDI_VISTA（0x06000000） | 0x0600 |
| Windows 7 | 0x0601 | NTDDI_WIN7（0x06010000） | 0x0800 |
| Windows 8 | 0x0602 | NTDDI_WIN8（0x06020000） | 0x0A00 |
| Windows 8.1 | 0x0603 | NTDDI_WINBLUE（0x06030000） | 0x0A00 |
| Windows 10 | 0x0A00 | NTDDI_WIN10（0x0A000000） | 0x0A00 |
| Windows 11 | 0x0A00 | NTDDI_WIN11（0x0A00000A 起） | 0x0A00 |
SDK 头文件在 WinSDKVer.h 和 SDKDDKVer.h 里做了"彼此推导"：你只定义 NTDDI_VERSION，它能倒推出 _WIN32_WINNT 和 WINVER；你只定义 _WIN32_WINNT，WINVER 也会被补上。反过来不行——NTDDI 的粒度太细，光靠 _WIN32_WINNT 推断不出 SP 层。问题是"推导"这件事依赖 SDK 的具体版本，换一套 SDK 行为就可能不一样，最稳的做法是四个宏全部显式写死。
注意：如果一个都不定义，老 SDK 默认值往往停在 XP 级（0x0501），新 SDK 默认值更靠后。别赌默认值，尤其跨机器构建时，A 机器 SDK 老一套、B 机器 SDK 新一套，同一个"没设宏"的工程编出来 API 可见面都不一样，这就是很多"换机器就报错"项目的源头。
3. 版本宏是怎么改变"同一份头文件"的
3.1 头文件里的 #if 门闩
把 windows.h 展开，你会看到大量这种段落（示意，非逐字原文）：
#if (_WIN32_WINNT >= 0x0600) WINBASEAPI ULONGLONG WINAPI GetTickCount64(void); #endif #if (_WIN32_WINNT >= 0x0A00) WINBASEAPI HRESULT WINAPI SetThreadDescription(HANDLE hThread, PCWSTR lpThreadDescription); #endif这是最典型的"版本门闩"。预处理阶段，编译器把 _WIN32_WINNT 替换成你定义的值，再和 0x0600、0x0A00 这些门槛比较，满足条件的段落才进入编译。所以你先 include windows.h 还是先定义宏，结果天差地别。预处理器只对"include 这一刻"的宏值负责，include 之后你再把宏从 0x0601 改成 0x0A00 已经来不及了。
这个机制也解释了为什么工程里要搞 pch.h 或者 targetver.h——它们就是用来保证"宏定义永远在所有 SDK 头文件之前生效"的。
3.2 MSDN 的 "Minimum supported client" 就是门槛值
查任何一个 Windows API 的文档，页面底部都有一行"Minimum supported client"，那行字就是你在头文件里需要的版本门槛，只不过写的是系统名而不是宏值。我整理几个常见对应关系：
| 函数/结构 | 最低支持系统 | 对应编译门槛 |
|---|---|---|
| GetTickCount64 | Windows Vista | _WIN32_WINNT >= 0x0600 |
| InitializeCriticalSectionEx | Windows Vista | _WIN32_WINNT >= 0x0600 |
| GetSystemTimePreciseAsFileTime | Windows 8 | _WIN32_WINNT >= 0x0602 |
| SetThreadDescription | Windows 10 | _WIN32_WINNT >= 0x0A00 |
| STARTUPINFOEXW 结构 | Windows Vista | _WIN32_WINNT >= 0x0600 |
所以当你看到一个"未声明标识符"报错，第一件事不是去翻代码，而是去翻文档底部那一行。它已经把答案告诉你了。
3.3 编译期定版本，运行期定策略
如果你把 _WIN32_WINNT 抬到 0x0A00 去调用 SetThreadDescription，程序拿到 Win7 机器上跑，加载器会在 PE 导入表里找 KERNEL32.dll 的这个导出函数，找不到就弹"无法定位程序输入点 SetThreadDescription 于动态链接库 KERNEL32.dll 上"。这就是静态导入的特点：程序在开始执行之前就已经死了，你写任何运行期 if 判断都救不回来。
真正要兼容老系统，有两个变通方案。
方案一：保持低版本宏，动态加载。示例：
using SetThreadDescriptionFn = HRESULT (WINAPI *)(HANDLE, PCWSTR); bool SetMyThreadDescription(PCWSTR desc) { HMODULE k32 = GetModuleHandleW(L"kernel32.dll"); auto fn = reinterpret_cast<SetThreadDescriptionFn>( GetProcAddress(k32, "SetThreadDescription")); if (fn) return SUCCEEDED(fn(GetCurrentThread(), desc)); return false; // 老系统不支持 }这段代码里你没用到头文件对 SetThreadDescription 的声明，宏设低一点也完全编译得过去，运行期查到函数指针才调用，查不到就安全降级。代价是多一点样板代码，换来的是整个程序的最低系统不用抬升。
方案二：用 Delay-Load，配合运行期检查。Delayload 让加载器在第一次调用时才解析符号，配合if (IsWindows10OrGreater())可以做到"新系统走新代码、老系统走老代码"。缺点是稍复杂，而且有些人不喜欢它带来的异常处理路径。
核心记忆点：编译期宏决定"这个二进制声明自己要什么"，运行期判断决定"当前机器给不给"。静态导入是前者主导的，别用后者去保护前者。
4. 实操：把目标版本写进项目
4.1 Visual Studio 图形界面里的配置
在 Visual Studio 里打开项目属性，路径是：C/C++ → 预处理器 → 预处理器定义。在这里追加一行（分号分隔）：
_WIN32_WINNT=0x0A00;WINVER=0x0A00;NTDDI_VERSION=0x0A000000;_WIN32_IE=0x0800如果定义列表里勾选了"从父级或项目默认值继承"，原来的WIN32;_DEBUG;_CONSOLE之类会一起出现，把新的追加在后面就行，不会覆盖旧的。
这里有个常见的混淆点：解决方案属性里那个"Windows SDK 版本"（比如 10.0.19041.0）选的是"用哪一套 SDK 头文件和库文件"，它决定文件从哪来；版本宏决定"这些文件对你开多少扇门"。两个按钮各有各的职责，不能互相替代。你选了最新的 SDK 版本，不代表你的代码就能用所有新 API——宏没抬到对应门槛，声明照样藏着。
4.2 pch.h 里写一版"版本声明区"
用预编译头的工程，最干净的做法是在 pch.h 最顶部放一个版本声明区，任何其他头文件 include 之前先执行：
// pch.h —— 必须放在所有 #include 之前 #pragma once #ifdef WINVER #undef WINVER #endif #ifdef _WIN32_WINNT #undef _WIN32_WINNT #endif #ifdef NTDDI_VERSION #undef NTDDI_VERSION #endif #ifdef _WIN32_IE #undef _WIN32_IE #endif // 目标系统：Windows 7 及以上 #define WINVER 0x0601 #define _WIN32_WINNT 0x0601 #define NTDDI_VERSION 0x06010000 #define _WIN32_IE 0x0800 #include <windows.h> // ... 其他全局头文件这样整条编译链从头到尾都只用这一套值，命令行里的 /D 和某个第三方头文件里偷偷 define 的宏，都会被这里统一接管。老工程没有 pch.h，用的是 stdafx.h + targetver.h 的组合，本质上也是干这件事，把上面这段塞进 targetver.h 即可。
我踩过的最贵一坑：在 .cpp 文件中部 define 宏，期望它影响后面某个头文件里的判断。结果 windows.h 早被预编译头拉进来过，我的定义根本没机会参与门闩判断。所以版本宏的位置必须"唯二"：项目定义区或 pch/targetver 的头部。
4.3 CMake、命令行与新式构建的写法
CMake 在 target 上声明最清楚，构建系统会自动传给编译器：
target_compile_definitions(MyApp PRIVATE WINVER=0x0A00 _WIN32_WINNT=0x0A00 NTDDI_VERSION=0x0A000000 _WIN32_IE=0x0800 )如果项目是用 CMake 构建，但又没走 target_compile_definitions，命令行直接加也可以：
cl /D_WIN32_WINNT=0x0A00 /DWINVER=0x0A00 /DNTDDI_VERSION=0x0A000000 /D_WIN32_IE=0x0800 main.cpp用 MinGW-w64 的话，gcc 的写法是-D_WIN32_WINNT=0x0A00 -DWINVER=0x0A00 ...。这套宏设计本来就不挑编译器，只要是标准预处理器，逻辑都一样。
4.4 多目标兼容项目的版本策略
如果你维护的是一个会被很多老系统用户加载的 DLL 或组件，"最低支持系统"不是一个可以随便抬的值。我常用的决策规则非常简单：
- 要静态调用某个新 API：宏必须抬到该 API 门槛以上，同时整个程序的最低系统也跟着抬。编译和运行两头都要满足。
- 想保住老系统：要么不用这个 API，要么用 GetProcAddress 动态加载，要么 Delay-Load 加运行期判断，坚决不让静态导入表出现老系统没有的符号。
在这里要额外提醒：宏设低只是不开门，不等于"没用新 SDK"。你完全可以拿最新的 SDK、设最低的宏，这样既能修老 API 的 bug，又不会意外引入高版本要求。
5. 版本宏相关的报错与排查实录
5.1 常见报错速查表
| 报错/现象 | 常见根因 | 处理方向 |
|---|---|---|
| C2065 / C3861：xxx undeclared identifier | 版本宏低于 API 门槛，头文件根本没声明 | 查 MSDN 最低系统，调高对应宏 |
| C1189 #error：Please define WINVER or _WIN32_WINNT... | 宏缺失，或 SDK 默认值不满足 | 在 pch/命令行显式定义一套值 |
| C4430 / C2146 类型诡异报错 | 结构体类型或字段因门槛被隐藏 | 同 C2065，检查对应结构所需版本 |
| LNK2019 / LNK2001 未解析外部符号 | 声明窗口和导入库版本不一致 | 检查 #pragma comment(lib) 和链接库配置 |
| 运行时报"无法定位程序输入点" | 编译目标高于实际运行系统 | 降低宏，或改 GetProcAddress 动态加载 |
| 同工程换机器后报错变化 | 依赖默认宏值，SDK 版本不同默认不同 | 所有宏显式写死 |
5.2 三个最容易踩的坑
坑一：include windows.h 之后才定义宏。很多人把宏写在某 .cpp 的中部，结果 windows.h 早就被 pch 或更早的 include 拉进过，预处理器见到你的宏时，文件级的 #if 已经执行完。记住：先宏后头文件，顺序是铁律。
坑二：只升 _WIN32_WINNT 却忘了 NTDDI_VERSION。有些 API 的门闩用的是 NTDDI_VERSION 判断。你只改了 _WIN32_WINNT，NTDDI 还是旧值，函数照样藏起来。反过来只在 NTDDI 设新值但 _WIN32_WINNT 拖后腿，SDK 头文件会得到自相矛盾的输入，也容易出现奇怪的 C1189。统一写一套是最省事的。
坑三：用运行期 if 判断"保护"静态导入。PE 导入表在加载阶段就要找齐所有符号，你的if (IsWindows10OrGreater()) SetThreadDescription(...)完全阻止不了程序在 Win7 上直接启动失败。记住前面那句话：静态导入由编译期宏主导，运行期判断保护不了它。
5.3 一次完整的排查演示
假设某次编译报 C2065：'GetTickCount64'： undeclared identifier。我会按这个流程走：
第一步，查 MSDN。打开 GetTickCount64 的文档页，底部 Minimum supported client 写的是 Windows Vista。于是知道门槛是_WIN32_WINNT >= 0x0600。
第二步，全局搜索 _WIN32_WINNT。把工程里所有定义处找出来：属性页、命令行参数、pch.h、targetver.h，一处都不能漏。如果存在多处定义，注意预处理器"后定义者覆盖"的规则，但真正起作用的是"include 那一刻的最新值"。所以我一般建议只留一处权威定义。
第三步，打开预处理输出。Visual Studio 的 C/C++ → 预处理器 → "预处理到文件"改成"是"，编译一次会生成 .i 文件。在这个文件里直接搜 GetTickCount64，如果搜不到，说明门闩确实没开，不需要猜了。
第四步，把宏统一改成 0x0600 以上的一整套值，重新编译。如果工程还要在 XP 上跑，那就改成动态加载，而不是抬全工程最低版本。
这套流程我在好几个项目里验证过，十分钟内基本能定位到根因。
6. 我自己的实操习惯
最后再聊一点个人习惯。我现在维护的老组件要兼容 Win7，所以宏常年写在 pch 里，固定是 0x0601 那一套。每次要加新 API，我第一件事就是看 MSDN 底部的最低系统，只要不是 Win7 以内，我就默认走 GetProcAddress，而不是去抬宏。这个习惯帮我把"最低支持系统"的口径守住了，也少了很多跨系统测试的返工。
另外我习惯在 pch 的版本声明区上面留一段注释，写清楚"这里的目标系统是 XX，为什么不是 XX，下次要改时注意影响"，相当于给未来的自己留个路标。一组宏本身没几行，难的是让人知道它为什么是这几个数。这个注释在团队协作里特别值钱。
还有一个小技巧：升级 Windows SDK 时，如果项目所有宏都是显式写死的，升级以后基本不会出惊喜；如果依赖了默认值，老项目可能突然开始走新版头文件的默认分支，行为就悄悄地变了。所以我接手任何一个 Win32 工程，第一件事永远是确认版本宏有没有全部显式定义。这一步做完，后面能少踩一半的玄学报错。
