一、背景AWTK 是 ZLG致远电子开源的跨平台 GUI 框架采用 LGPL 协议官方定位是嵌入式与桌面通用。官方入门文档《初识 AWTK》对 Windows 下环境要求的描述比较简明但文档的示例环境停留在几年前示例 Python 是 3.8示例 SCons 是 4.3.0。当操作系统和工具链都升到最新Windows 11 25H2、Python 3.14、SCons 4.11之后按文档走会遇到几个文档里完全没有记载的问题。本文完整记录在如下环境中的部署过程所有命令和输出均为实际执行结果读者可以逐步对照复现项目版本操作系统Windows 11 25H2Python3.1464 位开发工具AWStudio内置 AWTK 1.7.1 SDK编译器Visual Studio 2022 CommunityMSVC 14.4xSCons最终固定为 4.7.0初始安装的是 4.11.1后降级部署过程中一共遇到四个问题按出现顺序逐一展开。前两个是老生常谈的安装位置问题第三个涉及微软对 WMIC 的产品决策第四个最有分析价值SCons 4.8.0 改变了TOOLSNone参数的语义直接导致 AWTK 1.7.1 的官方构建脚本无法工作。二、按官方文档安装与第一次检测2.1 官方文档的安装步骤官方文档《初识 AWTK》环境搭建Windows x64一节列出的步骤如下我按顺序执行并标注实际情况步骤官方要求官方示例版本本文实际版本1. 安装 Pythonx64 版本≥ 2.7需加入系统环境变量3.8.2 amd643.14.62. 安装 SCons≥ 3.0.0先装 Python 再装 SCons4.3.04.11.1后降级到 4.7.03. 安装 Visual Studio≥ 2015VS2015 需自定义安装勾选 Visual C—VS2022 Community4. 安装 Node.js≥ 10.0.0安装器自动添加环境变量12.18.1 x64已安装官方文档还给了两条容易被忽略的提醒这里原样强调源码路径不要包含中文否则编译阶段会出现莫名错误从 GitHub 下载 ZIP 包的解压后目录名带-master后缀需要手动改名为awtk。关于 SCons 的安装方式官方文档写的是下载压缩包解压后在目录内执行python setup.py install这与pip install scons等价本文使用 pip 方式。关于 Visual StudioVS2019 及以上版本对应勾选使用 C 的桌面开发工作负载。工作负载Workload是 Visual Studio 安装器里的组件分组概念新版安装器不再整包安装而是把某一类开发用途所需的组件打包成一个个可勾选的集合使用 C 的桌面开发这一项就包含 MSVC 编译器cl.exe、Windows SDK、CMake 与调试器等。只装 VS 本体而不勾选任何工作负载磁盘上不会有 C 编译器后面 SCons 编译时也就找不到工具链。另外官方 FAQ 补充了一条版本约束VS2019 需要 SCons 不低于 3.1.0VS2022 需要 SCons 不低于 4.3.0。2.2 环境检测工具的第一次结果AWStudio / AWTK Designer 自带环境检测工具即官方文档提到的 awtk-tools-checker安装完成后运行自检。第一次检测结果环境官方要求检测结果Python≥ 2.7x64通过SCons≥ 3.0.0未通过编译器推荐使用 Visual Studio C未通过Visual Studio C≥ 2015未通过MinGW可选项未通过OpenGL 驱动≥ 2.0.0通过Node.js≥ 10.0.0通过VC 运行时—通过reg.exe—通过WMIC.exe—未通过PowerShell—通过实际上这台机器的 Visual Studio 2022 Community 和 C 工具集是完好的第四节给出验证方法检测未通过另有原因。下面按排查顺序逐一展开。三、SCons 未通过装到了哪里PATH 里有没有pip install scons执行完不代表检测工具能找到它。这一步失败通常是两个原因叠加。第一pip 本身可能是用户级安装。检查方法pip --version如果输出中的路径位于C:\Users\你的用户名\AppData\Roaming\Python\...说明 pip 在用户目录下。这种情况下不带管理员执行pip install包会继续装进用户目录scons.exe会落在用户目录的 Scripts 文件夹下而这个目录默认不在 PATH 环境变量里命令行和检测工具都找不到它。第二检测工具不会热刷新环境变量。它启动时继承的是当时系统 PATH 的快照装完东西再点检测按钮用的还是旧 PATH。所以每装完一个工具必须把检测工具完全关闭再重新打开。正确的安装步骤在开始按钮上右键选择终端(管理员)执行python -m pip install scons执行scons --version确认版本号完全关闭检测工具重新打开再点检测。版本选择上注意官方 FAQ 的约束VS2022 需要 SCons 不低于 4.3.0所以不要装 3.x 求稳但也不要直接装最新版原因见第七节。四、编译器未通过先确认 VS 本体和工具集是否完好检测项编译器未通过并不一定代表 Visual Studio 没装。可以用微软官方的 vswhere 工具核实VS 安装时自带固定路径C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe -all -products * -property displayName本文机器输出Visual Studio Community 2022。再确认 C 工具集MSVC是否安装直接找 cl.exedir C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC /b输出形如14.44.35207的版本目录说明 MSVC 工具集存在编译器本体没有问题。那么检测项为什么标红两个可能一是检测工具启动时环境未刷新关闭重开即可解决二是 SCons 缺失导致的连锁判定——官方 FAQ 提到 VS2022 需要配合 SCons 4.3.0 以上版本检测工具的编译器项与 SCons 存在联动。实际处理顺序是先装好 SCons关掉重开检测工具Visual Studio C这一项就会通过。至于 MinGW它和 Visual Studio C 是二选一的关系有 VS 就不需要安装该项保持未通过不影响任何功能。五、WMIC 未通过微软已经把它删了而且装不回来这一项最容易误判成自己忘了装。实际原因是微软的产品决策官方公告《从 Windows 中删除 WMIC》2025 年 9 月宣布 WMIC 从 Windows 11 中移除24H2 起默认不装后续更新分阶段删除。2026 年 8 至 9 月的累积更新KB5067470、KB5120998、KB5124008 一族完成了最后一步。如果机器装了这一族更新就会遇到下述现象。5.1 现象按常规方法恢复 WMICAdd-WindowsCapability-Online-NameWMIC~~~~0.0.1.0执行成功输出Path : Online : True RestartNeeded : False但验证文件是否存在Test-PathC:\Windows\System32\wbem\WMIC.exe输出False。反复安装结果相同命令永远成功文件永远不出现。5.2 排查过程第一步查组件维护日志看安装事务到底做了什么。CBS 日志位于C:\Windows\Logs\CBS\CBS.log用 findstr 过滤findstr /i WMIC C:\Windows\Logs\CBS\CBS.log关键输出有两类。一类表明功能包处于已暂存但未启用状态CBS Skip FODs not currently installed: Microsoft-Windows-WMIC-FoD-Package~...~10.0.26100.1742, state: Staged另一类暴露了一个值得注意的机制——安装流程会检查一个注册表值Registry value does not exist, key: Microsoft\Wbem\CIMOM, value name: DisableAutomaticWMICRemoval从值名看这是系统预留的禁止自动移除 WMIC开关。尝试设置它并重装reg addHKLM\SOFTWARE\Microsoft\Wbem\CIMOM/v DisableAutomaticWMICRemoval/t REG_DWORD/d 1/fAdd-WindowsCapability-Online-NameWMIC~~~~0.0.1.0Restart-ServiceWinMgmt-Force结果文件依然不出现。这个开关只在早期的 Insider 预览版本中有效正式版本已经不认它了。第二步直接检查组件仓库 WinSxS 里还有没有 WMIC 功能包的实际文件dir C:\Windows\WinSxS /b | findstr /i wmic-fod输出为空。作为对照系统里与 WMI 相关的其余组件都健在。结论这批累积更新已经把 WMIC 按需功能包的实际文件从系统里删除只留下一个空的注册登记项。这就是为什么安装命令显示成功——系统确实登记了但已经无货可装。5.3 结论与建议不要在恢复 WMIC 上继续花时间。卸载更新再从旧 ISO 离线注入功能包在技术上可行但下一次月度更新会再删一次没有长期价值。对 AWTK 开发而言WMIC 只是检测工具清单中的一项部分老脚本用它查询系统信息AWTK 本身的编译链是 SCons 加 Visual Studio完全不依赖 wmic。这一项红着直接忽略即可。真正需要查询系统信息时PowerShell 的 CIM 命令可以完成同样的工作例如Get-CimInstance Win32_OperatingSystem。六、编译阶段的问题AttributeError: Builder or other environment method ‘Library’ not found以上问题解决后检测工具除了 MinGW 和 WMIC 两项均可无视外全部通过。然而触发编译立刻报错File C:/AWStudio/AWTK/SDK/awtk/3rd/nanovg/SConscript, line 13: env.Library(os.path.join(LIB_DIR, nanovg), Glob(base/*.c)) File C:\Python314\Lib\site-packages\SCons\Environment.py, line 1445: raise AttributeError( AttributeError: Builder or other environment method Library not found. Check spelling, check external program exists in env[ENV][PATH], and check that a suitable tool is being loadedenv.Library是 SCons 最基础的构建器不存在拼写错误的可能。这个报错说明 MSVC 工具链没有被加载进构建环境。排查分三步。6.1 查看报错的源头直接阅读 SCons 源码Environment.py第 1434 行起def__getattr__(self,name:str)-NoReturn:Handle missing attribute in an environment. ... .. versionadded:: 4.10.0 raiseAttributeError(fBuilder or other environment method{name!r}not found.\nCheck spelling, check external program exists in env[ENV][PATH],\nand check that a suitable tool is being loaded)fromNone注释标明这段代码是 4.10.0 新增的。它印证了报错的真实含义环境里不存在名为Library的构建器也就是工具链加载这一步没有发生。6.2 查看 AWTK 的构建脚本AWTK 根目录的 SConstruct 开头如下importosimportawtk_configasawtk APP_TOOLSNoneifawtk.TOOLS_NAME!:APP_TOOLS[awtk.TOOLS_NAME]awtk.genIdlAndDef();DefaultEnvironment(TOOLSAPP_TOOLS,CCFLAGSawtk.AWTK_CCFLAGS,...)TOOLS_NAME默认是空字符串awtk_config_common.py 中TOOLS_NAME 切换 MinGW 的TOOLS_NAME mingw一行默认处于注释状态因此实际传入的是TOOLS None。在 SCons 3.x 到 4.7.x 的行为里这等价于不指定即加载默认工具链Windows 上会自动探测并加载 MSVC。AWTK 1.7.1 发布于 2022 年 10 月这个写法在当时的语义下没有任何问题。6.3 对照实验为了把语义变化钉死构造一个最小复现。新建临时目录写入如下 SConstructenvDefaultEnvironment(TOOLSNone)print(BUILDERS_COUNT ,len(env[BUILDERS]))在该目录执行scons。再用不传参数的版本对照envDefaultEnvironment()print(BUILDERS_COUNT ,len(env[BUILDERS]))在 SCons 4.11.1 下实验一输出BUILDERS_COUNT 0实验二输出 25包含 Library、StaticLibrary、Program 等。结论显式传TOOLSNone时SCons 4.11 一个工具都不加载不传则正常加载默认工具链。随后把不同版本的 SCons 分别安装到临时目录pip install --target方式不污染主环境用同一脚本逐一测试结果如下SCons 版本TOOLSNone 时的构建器数量是否兼容 Python 3.144.11.10工具链不加载是4.9.10工具链不加载是4.8.10工具链不加载是4.7.025老语义正常是行为变化发生在 SCons 4.8.0。4.7.0 是保留老语义的最新版本且在 Python 3.14 下运行正常同时满足 AWTK 官方VS2022 需要 SCons 不低于 4.3.0的要求。6.4 修复方案两种方案都有效按实际情况选择。方案一修改 AWTK 的 SConstruct把第 4 行改为APP_TOOLS[default]语义与老版本完全一致可以继续使用任意新版 SCons。缺点是改动了厂商 SDK 文件AWTK 升级后会被覆盖需要重打。方案二降级 SConspython-m pip uninstall-y scons python-m pip installscons4.7.0scons--version保持 SDK 原样缺点是绑定了较旧的 SCons。两种方案的选择依据可以归纳为对比项方案一改脚本方案二降级 SConsSDK 文件是否改动是升级 AWTK 后需重打否保持原样SCons 版本任意新版无上限固定 4.7.0适用场景本机还有其他项目必须用新 SCons以 AWTK 开发为主希望 SDK 干净后续维护成本每次 AWTK 升级检查一次注意不要误执行pip install -U scons本文选择了方案二。理由AWTK SDK 是整体发布的保持文件原样便于日后整体升级4.7.0 发布于 2024 年 3 月并不算旧且明确满足官方版本要求。降级完成后在 awtk 根目录重新编译一次通过。七、编译验证命令行方式验证AWStudio 内编译等价cd C:\AWStudio\AWTK\SDK\awtk scons -j8正常结束时输出scons: done building targets.。产物检查lib目录生成全套静态库awtk_global.lib、tkc_core.lib、nanovg.lib、agge.lib、SDL2.lib、mbedtls.lib 等bin目录生成可执行文件demo1.exe、demo_basic.exe、demo_animator.exe 等示例以及 strgen.exe、xml_to_ui.exe 等代码生成工具。双击bin\demo_basic.exe可以看到 AWTK 的演示界面说明从编译到链接到运行整条链路正常。八、避坑要点汇总把本文的四个问题浓缩成一张速查表现象根因解决方案SCons 已安装检测工具报未通过包装进用户目录Scripts 不在 PATH或检测工具未重启管理员安装到系统 Python检测工具关闭重开VS2022 已装编译器检测未通过检测与 SCons 版本存在联动装好 SCons 后重开检测工具用 vswhere 确认 VS 本体WMIC 检测未通过2026 年更新已移除 WMIC 且功能包被掏空无视该行改用 PowerShell CIM 命令编译报 AttributeError: Library not foundSCons 4.8 起TOOLSNone语义变化固定 SCons 4.7.0或将 SConstruct 的APP_TOOLS None改为[default]补充几条通用建议Python 包用管理员权限安装到系统 Python避免装进不在 PATH 上的用户目录每装完一个工具完全关闭检测工具再重新打开检测升级 AWTK SDK 之后重新检查 SConstruct 对TOOLS的处理方式再决定是否把 SCons 升回去官方文档的既有要求依然有效源码路径不要包含中文从 GitHub 下载 ZIP 的需要把 awtk-master 改名为 awtkVS2019 及以上需要勾选使用 C 的桌面开发工作负载工作负载即安装器里按用途打包的组件集合不勾选就不会装上 MSVC 编译器详见 2.1 节。九、参考资料AWTK 官方入门文档《初识 AWTK》https://awtk.zlg.cn/docs/awtk_docs/AWTK_Guide/1.GettingStarted.htmlAWTK 官网及环境搭建 FAQhttps://awtk.zlg.cnAWTK 源码仓库https://github.com/zlgopen/awtk微软官方公告《从 Windows 中删除 WMIC》https://support.microsoft.com/zh-cn/servicing/os/windows/docs/2025/09/windows-management-instrumentation-command-line-wmic-removal-from-windowsSCons 官方网站https://scons.org/下一篇预告环境就绪之后下一篇文章梳理 AWTK 1.7.1 的工程目录结构、SCons 构建体系以及 awtk_config.py 的关键配置项然后写出第一个 AWTK 应用。