企业官网建设流程全解析

一、背景

AWTK 是 ZLG（致远电子）开源的跨平台 GUI 框架，采用 LGPL 协议，官方定位是嵌入式与桌面通用。官方入门文档《初识 AWTK》对 Windows 下环境要求的描述比较简明，但文档的示例环境停留在几年前：示例 Python 是 3.8，示例 SCons 是 4.3.0。当操作系统和工具链都升到最新（Windows 11 25H2、Python 3.14、SCons 4.11）之后，按文档走会遇到几个文档里完全没有记载的问题。

本文完整记录在如下环境中的部署过程，所有命令和输出均为实际执行结果，读者可以逐步对照复现：

部署过程中一共遇到四个问题，按出现顺序逐一展开。前两个是老生常谈的安装位置问题，第三个涉及微软对 WMIC 的产品决策，第四个最有分析价值：SCons 4.8.0 改变了TOOLS=None参数的语义，直接导致 AWTK 1.7.1 的官方构建脚本无法工作。

二、按官方文档安装与第一次检测

2.1 官方文档的安装步骤

官方文档《初识 AWTK》"环境搭建（Windows x64）"一节列出的步骤如下，我按顺序执行并标注实际情况：

官方文档还给了两条容易被忽略的提醒，这里原样强调：

• 源码路径不要包含中文，否则编译阶段会出现莫名错误；
• 从 GitHub 下载 ZIP 包的，解压后目录名带-master后缀，需要手动改名为awtk。

关于 SCons 的安装方式，官方文档写的是下载压缩包解压后在目录内执行python setup.py install，这与pip install scons等价，本文使用 pip 方式。关于 Visual Studio，VS2019 及以上版本对应勾选"使用 C++ 的桌面开发"工作负载。工作负载（Workload）是 Visual Studio 安装器里的组件分组概念：新版安装器不再整包安装，而是把某一类开发用途所需的组件打包成一个个可勾选的集合，"使用 C++ 的桌面开发"这一项就包含 MSVC 编译器（cl.exe）、Windows SDK、CMake 与调试器等。只装 VS 本体而不勾选任何工作负载，磁盘上不会有 C++ 编译器，后面 SCons 编译时也就找不到工具链。另外官方 FAQ 补充了一条版本约束：VS2019 需要 SCons 不低于 3.1.0，VS2022 需要 SCons 不低于 4.3.0。

2.2 环境检测工具的第一次结果

AWStudio / AWTK Designer 自带环境检测工具（即官方文档提到的 awtk-tools-checker），安装完成后运行自检。第一次检测结果：

实际上这台机器的 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。所以每装完一个工具，必须把检测工具完全关闭再重新打开。

正确的安装步骤：

1. 在开始按钮上右键，选择"终端(管理员)"；
2. 执行python -m pip install scons；
3. 执行scons --version确认版本号；
4. 完全关闭检测工具，重新打开，再点"检测"。

版本选择上注意官方 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.exe：

dir "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 现象

按常规方法恢复 WMIC：

Add-WindowsCapability-Online-Name"WMIC~~~~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 add"HKLM\SOFTWARE\Microsoft\Wbem\CIMOM"/v DisableAutomaticWMICRemoval/t REG_DWORD/d 1/fAdd-WindowsCapability-Online-Name"WMIC~~~~0.0.1.0"Restart-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 loaded

env.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(f"Builder or other environment method{name!r}not found.\n""Check spelling, check external program exists in env['ENV']['PATH'],\n""and check that a suitable tool is being loaded")fromNone

注释标明这段代码是 4.10.0 新增的。它印证了报错的真实含义：环境里不存在名为Library的构建器，也就是工具链加载这一步没有发生。

6.2 查看 AWTK 的构建脚本

AWTK 根目录的 SConstruct 开头如下：

importosimportawtk_configasawtk APP_TOOLS=Noneifawtk.TOOLS_NAME!='':APP_TOOLS=[awtk.TOOLS_NAME]awtk.genIdlAndDef();DefaultEnvironment(TOOLS=APP_TOOLS,CCFLAGS=awtk.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 对照实验

为了把语义变化钉死，构造一个最小复现。新建临时目录，写入如下 SConstruct：

env=DefaultEnvironment(TOOLS=None)print('BUILDERS_COUNT =',len(env['BUILDERS']))

在该目录执行scons。再用不传参数的版本对照：

env=DefaultEnvironment()print('BUILDERS_COUNT =',len(env['BUILDERS']))

在 SCons 4.11.1 下，实验一输出BUILDERS_COUNT = 0，实验二输出 25（包含 Library、StaticLibrary、Program 等）。结论：显式传TOOLS=None时，SCons 4.11 一个工具都不加载；不传则正常加载默认工具链。

随后把不同版本的 SCons 分别安装到临时目录（pip install --target方式，不污染主环境），用同一脚本逐一测试，结果如下：

行为变化发生在 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 升级后会被覆盖，需要重打。

方案二，降级 SCons：

python-m pip uninstall-y scons python-m pip install"scons==4.7.0"scons--version

保持 SDK 原样，缺点是绑定了较旧的 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 的演示界面，说明从编译到链接到运行整条链路正常。

八、避坑要点汇总

把本文的四个问题浓缩成一张速查表：

补充几条通用建议：

1. Python 包用管理员权限安装到系统 Python，避免装进不在 PATH 上的用户目录；
2. 每装完一个工具，完全关闭检测工具再重新打开检测；
3. 升级 AWTK SDK 之后，重新检查 SConstruct 对TOOLS的处理方式，再决定是否把 SCons 升回去；
4. 官方文档的既有要求依然有效：源码路径不要包含中文；从 GitHub 下载 ZIP 的需要把 awtk-master 改名为 awtk；VS2019 及以上需要勾选"使用 C++ 的桌面开发"工作负载（工作负载即安装器里按用途打包的组件集合，不勾选就不会装上 MSVC 编译器，详见 2.1 节）。

九、参考资料

• AWTK 官方入门文档《初识 AWTK》：https://awtk.zlg.cn/docs/awtk_docs/AWTK_Guide/1.GettingStarted.html
• AWTK 官网及环境搭建 FAQ：https://awtk.zlg.cn
• AWTK 源码仓库：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-windows
• SCons 官方网站：https://scons.org/

下一篇预告

环境就绪之后，下一篇文章梳理 AWTK 1.7.1 的工程目录结构、SCons 构建体系以及 awtk_config.py 的关键配置项，然后写出第一个 AWTK 应用。