★ FEATURED ARTICLE 写 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 一套头文件服务二十多年的 APIWindows 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 表示 XP0x0600 表示 Vista0x0601 表示 Win70x0602 表示 Win80x0603 表示 Win8.10x0A00 表示 Win10/Win11。Windows 10 开始主版本号直接跳到 10所以是 0x0A00这个别按十进制去理解它不是一万人就是十六进制的 10。2.2 NTDDI_VERSION把补丁级都算进去NTDDI_VERSION 是这四个宏里粒度最细的。它不光管主次版本还把服务包SP和功能更新的层级也编进数值里。格式上大致是主版本、次版本、SP/构建层压成一个 32 位整数0x06010000 是 Win70x06020000 是 Win80x0A000000 是 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 Controlscomctl32和部分 Shell 相关头文件里能看到多新的界面特性。取值用的是 IE 版本号做锚点0x0400 对应 IE 4.00x0500 对应 IE 5.00x0600 对应 IE 6.00x0800 对应 IE 8.00x0A00 对应 IE 11。这串值看着像浏览器历史实际含义是使用这一层公共控件的界面能力。很多现代界面代码需要设一个较新的 _WIN32_IE否则连 ListView_SetView 这种站在 IE 5.01 门槛上的宏都看不见。它是四兄弟里最容易被漏掉的但漏掉的结果往往不是报错而是控件行为悄悄变老——最坑。2.4 一张表把取值和换算说清目标系统WINVER / _WIN32_WINNTNTDDI_VERSION 别名值_WIN32_IE 建议Windows 20000x0500NTDDI_WIN2K0x050000000x0400Windows XP0x0501NTDDI_WINXP0x050100000x0500Windows Server 20030x0502NTDDI_WS030x050200000x0500Windows Vista0x0600NTDDI_VISTA0x060000000x0600Windows 70x0601NTDDI_WIN70x060100000x0800Windows 80x0602NTDDI_WIN80x060200000x0A00Windows 8.10x0603NTDDI_WINBLUE0x060300000x0A00Windows 100x0A00NTDDI_WIN100x0A0000000x0A00Windows 110x0A00NTDDI_WIN110x0A00000A 起0x0A00SDK 头文件在 WinSDKVer.h 和 SDKDDKVer.h 里做了彼此推导你只定义 NTDDI_VERSION它能倒推出 _WIN32_WINNT 和 WINVER你只定义 _WIN32_WINNTWINVER 也会被补上。反过来不行——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那行字就是你在头文件里需要的版本门槛只不过写的是系统名而不是宏值。我整理几个常见对应关系函数/结构最低支持系统对应编译门槛GetTickCount64Windows Vista_WIN32_WINNT 0x0600InitializeCriticalSectionExWindows Vista_WIN32_WINNT 0x0600GetSystemTimePreciseAsFileTimeWindows 8_WIN32_WINNT 0x0602SetThreadDescriptionWindows 10_WIN32_WINNT 0x0A00STARTUPINFOEXW 结构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(Lkernel32.dll); auto fn reinterpret_castSetThreadDescriptionFn( 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_WINNT0x0A00;WINVER0x0A00;NTDDI_VERSION0x0A000000;_WIN32_IE0x0800如果定义列表里勾选了从父级或项目默认值继承原来的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 WINVER0x0A00 _WIN32_WINNT0x0A00 NTDDI_VERSION0x0A000000 _WIN32_IE0x0800 )如果项目是用 CMake 构建但又没走 target_compile_definitions命令行直接加也可以cl /D_WIN32_WINNT0x0A00 /DWINVER0x0A00 /DNTDDI_VERSION0x0A000000 /D_WIN32_IE0x0800 main.cpp用 MinGW-w64 的话gcc 的写法是-D_WIN32_WINNT0x0A00 -DWINVER0x0A00 ...。这套宏设计本来就不挑编译器只要是标准预处理器逻辑都一样。4.4 多目标兼容项目的版本策略如果你维护的是一个会被很多老系统用户加载的 DLL 或组件最低支持系统不是一个可以随便抬的值。我常用的决策规则非常简单要静态调用某个新 API宏必须抬到该 API 门槛以上同时整个程序的最低系统也跟着抬。编译和运行两头都要满足。想保住老系统要么不用这个 API要么用 GetProcAddress 动态加载要么 Delay-Load 加运行期判断坚决不让静态导入表出现老系统没有的符号。在这里要额外提醒宏设低只是不开门不等于没用新 SDK。你完全可以拿最新的 SDK、设最低的宏这样既能修老 API 的 bug又不会意外引入高版本要求。5. 版本宏相关的报错与排查实录5.1 常见报错速查表报错/现象常见根因处理方向C2065 / C3861xxx undeclared identifier版本宏低于 API 门槛头文件根本没声明查 MSDN 最低系统调高对应宏C1189 #errorPlease 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_WINNTNTDDI 还是旧值函数照样藏起来。反过来只在 NTDDI 设新值但 _WIN32_WINNT 拖后腿SDK 头文件会得到自相矛盾的输入也容易出现奇怪的 C1189。统一写一套是最省事的。坑三用运行期 if 判断保护静态导入。PE 导入表在加载阶段就要找齐所有符号你的if (IsWindows10OrGreater()) SetThreadDescription(...)完全阻止不了程序在 Win7 上直接启动失败。记住前面那句话静态导入由编译期宏主导运行期判断保护不了它。5.3 一次完整的排查演示假设某次编译报 C2065GetTickCount64 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 工程第一件事永远是确认版本宏有没有全部显式定义。这一步做完后面能少踩一半的玄学报错。
阅读完成 · 觉得有帮助？
