Q-IM GUI — Windows 交叉构建经验（2026-08 实测）¶

与 WINDOWS-BUILD-GUIDE.md（首版链路）互补。本文记录第二次完整构建（VM: Win11, 宿主: Linux）踩出的全部坑与解法，并产出可持续一键脚本 scripts/windows-build.ps1。

0. 一句话结论¶

qim-gui.exe（Tauri 2, target x86_64-pc-windows-gnu, zigbuild 工具链）在 Win11 VM 内构建， 必须三件套齐备：官方完整 zig 0.16.0 + GNU dlltool 工具链 + zig 环境变量注入。缺任一都会在中段失败。

1. 环境清单（VM 内一次性准备）¶

组件	版本/路径	说明
Rust + cargo	stable	rustup
cargo-zigbuild	0.23.0	`cargo install cargo-zigbuild`
zig 完整包	0.16.0 → `C:\zig`	必须官方完整 zip（lib 含 `compiler/aro` 等 2 万+ 文件）
GNU dlltool 工具链	`C:\tools\dlltool\`	dlltool.exe + as.exe + x86_64-w64-mingw32-as.exe + 5 个依赖 DLL
protoc	21.x → `C:\tools\protoc`	qim-proto 需要
Node	v18+	qim-gui 前端
链接器配置	`C:\qim4\.cargo\config.toml` + `zigcc.bat`	必须保留，同步源码时勿覆盖

dlltool 工具链 9 文件（GNU binutils 的 dlltool 是自包含 CLI，但依赖这些 DLL）： dlltool.exe、as.exe、x86_64-w64-mingw32-as.exe、 libzstd.dll、zlib1.dll、libintl-8.dll、libwinpthread-1.dll、libiconv-2.dll（另需一个 shim 令 rustc 找到 dlltool.exe）。

2. 一键构建¶

powershell -ExecutionPolicy Bypass -File scripts\windows-build.ps1            # 仅构建
powershell -ExecutionPolicy Bypass -File scripts\windows-build.ps1 -Upload     # 构建并回传宿主机

脚本幂等：已完成的阶段自动跳过（zig 已解压/已替换/dlltool 已配好）。

产物路径（workspace 级 target，不是 src-tauri/target）：

C:\qim4\target\x86_64-pc-windows-gnu\release\qim-gui.exe

3. 坑与解法（按构建顺序）¶

3.1 dlltool 三连坑（rustc 编译 windows-* crate 时）¶

现象：error calling dlltool / failed to add native library ...\kernel32.dll_imports.lib (os error 2)。

cargo-zigbuild 提供的 dlltool 不可用：zig dlltool 参数不兼容 rustc 的调用方式； C:\qim4\dlltool.exe 是 zig.exe 拷贝（假 dlltool），同名分派到 zig 主帮助。 → 用 GNU mingw-w64 binutils 的 dlltool.exe。
GNU dlltool 缺 as.exe：内部要调汇编器 → 补 as.exe（同一文件双命名）。
缺依赖 DLL 时进程静默失败：GUI 子系统程序不输出 stderr，$LASTEXITCODE 为空。 → 逐个补齐 5 个 DLL（上表）。

验证：where.exe dlltool 第一条必须是 C:\tools\dlltool\dlltool.exe （C:\qim4 在 PATH 中排前时会被假 dlltool 抢先）。

3.2 zig 精简安装缺 lib（`-target` 时报 unable to find zig installation directory）¶

现象：zig cc -v 正常，但 zig cc -target x86_64-windows-gnu ... 报 error: unable to find zig installation directory 'C:\zig\zig.exe'。根因：C:\zig\lib 是精简版，缺 compiler/aro 等目标解析必需文件。 → 换官方完整 zip（zig-x86_64-windows-0.16.0.zip，lib 下 2 万+ 文件）， Rename-Item C:\zig zig.old 备份后整体替换。

3.3 zigbuild 找不到 zig（`Failed to find zig`）¶

现象：tauri build --runner cargo-zigbuild → Error: Failed to find zig。根因：find_zig() 只查 PATH 的 zig 或 CARGO_ZIGBUILD_ZIG_PATH，脚本环境两者皆无。 → 构建前注入：

$env:PATH = "C:\zig;" + $env:PATH
$env:CARGO_ZIGBUILD_ZIG_PATH = "C:\zig\zig.exe"

3.4 其余¶

坑	解法
`Expand-Archive` 解 2 万文件卡死	用 `tar -xf`（Win11 自带 bsdtar）
`C:\` 根目录无写权限（UAC）	下载/中间产物一律放 `C:\qim4\`
PowerShell 把 clang `-v` 的 stderr 当错误	验证段临时 `$ErrorActionPreference="Continue"`，按 `$LASTEXITCODE` 判断
中文 IME 吞 `$_`/`-F` 等字符	任务栏切「英」或 Shift 切换，命令逐条核对 OCR
回传通道	宿主 `python3 -m uploadserver 8123`（cwd=/tmp/qim-out）；VM `curl.exe -F "files=@..." http://192.168.122.1:8123/upload`，204=成功

4. 运行验证¶

双击 qim-gui.exe（Win11 自带 WebView2）。
gateway 填宿主地址：192.168.122.1:7000（跨机器；本机则 127.0.0.1:7000）。
宿主 4 服务（session/mailbox/writer/gateway）须监听 0.0.0.0； gateway 客户端 7000 / push 7010 / token 8000 / metrics 9100。
预期：登录 → Online → 会话列表（单聊+群）→ 聊天窗口 → 群成员面板。

5. 遗留¶

docs/11-client-sdk.md 里程碑第 10 项「契约一致性测试」未做（可选后续）。
OBS（C:\Drivers\TwC\qI6Jwr3.exe，伪装进程）在 VM 中会自愈重建，删除需先禁持久化机制（计划任务/启动项）。