Q-IM GUI — Windows 构建与运行指引（实测可用）¶

本指引基于 Windows 11 VM 实测。Tauri 2 GUI 客户端（crates/qim-gui）在 Windows 上原生构建全链路已验证：qim-gui.exe 编译通过。关键结论：必须 tauri build（生产）而非 cargo build（dev 模式会去连 localhost:1420）。

1. 环境准备¶

组件	版本	获取
Rust	stable（MSVC 或 GNU）	rustup-init.exe
Node.js	v18+	node 官网免安装 zip
zig	0.16.0	https://ziglang.org/download/0.16.0/zig-x86_64-windows-0.16.0.zip
protoc	21.x	https://github.com/protocolbuffers/protobuf/releases/download/v21.12/protoc-21.12-win64.zip

:: 解压 zig 到 C:\zig，protoc 到 C:\tools\protoc
set PATH=C:\zig\zig-x86_64-windows-0.16.0;C:\tools\protoc\bin;%PATH%

2. 源码（必须保持 workspace 相对路径）¶

crates/qim-gui（含 src-tauri）依赖 qim-sdk（依赖 qim-proto/qim-codec）与 qim-common，另有主 Cargo.toml（workspace）。缺任何一个，cargo 加载 workspace 会报"failed to load manifest for workspace member"。

C:\qim\
  Cargo.toml            ← 主 workspace（members 含全部 crates）
  crates\
    qim-gui\            ← 前端（package.json + src/）+ src-tauri\
    qim-sdk\
    qim-proto\
    qim-codec\
    qim-common\
    qim-store\ ...      ← 其余 workspace member 也要（可空目录需含 Cargo.toml）

3. 构建（核心步骤）¶

:: 3.1 交叉编译工具（zig 做 linker/CC/dlltool）
cargo install cargo-zigbuild

:: 3.2 前端依赖 —— Windows 上必须重新 npm install！
::     （从 Linux 拷来的 node_modules/.bin 是 shell shim，Windows 找不到 tsc/vite）
cd C:\qim\crates\qim-gui
if exist node_modules rmdir /s /q node_modules
npm install
npm run build

:: 3.3 生产构建（产物加载嵌入的 dist，不是 localhost）
cd C:\qim\crates\qim-gui\src-tauri
tauri build --no-bundle --target x86_64-pc-windows-gnu

:: 产物
C:\qim\crates\qim-gui\src-tauri\target\x86_64-pc-windows-gnu\release\qim-gui.exe

cargo-zigbuild 自动处理 zig 的 linker/CC/dlltool/ar（GNU target 下 windows-sys 需要 dlltool，这是绕不开的一步）。

4. 运行与测试¶

双击 qim-gui.exe（Win11 自带 WebView2）。
登录栏 gateway 填宿主地址，如 192.168.122.1:7000（若连本机则是 127.0.0.1:7000）。

服务端 gateway 需监听 0.0.0.0（跨机器）：

QIM_GATEWAY_LISTEN=0.0.0.0:7000 QIM_GATEWAY_PUSH=0.0.0.0:7010 QIM_TOKEN_LISTEN=0.0.0.0:8000 ./target/release/qim-gateway

界面：登录后自动 Online → 会话列表（单聊+群）、聊天窗口、群成员面板、加群框。功能：单聊/群消息收发、群成员管理、历史消息。

5. 踩过的坑（实测记录）¶

坑	现象	解法
cargo build 是 dev 模式	窗口显示"无法访问 localhost:1420 拒绝连接"	必须 `tauri build`（生产，嵌入 dist）
node_modules 平台 shims	`'tsc' 不是内部或外部命令`	Windows 上 `npm install` 重装
cargo linker 数组不被接受	`config.toml: expected a string, but found a array`	linker 用字符串指向 `zigcc.bat` wrapper：`linker = "C:\\...\\zigcc.bat"`
gnu target 缺 dlltool	`error calling dlltool 'dlltool.exe': program not found`	用 `cargo-zigbuild`（自动配 zig dlltool）
zig argv[0] 分派名	复制 zig.exe 为 dlltool.exe 显示 zig 主帮助	不要用复制名；显式子命令（`zig dlltool`），cargo-zigbuild 封装
qim-proto 需 protoc	`Could not find 'protoc'`	装 protoc + PATH/`PROTOC` 环境变量
workspace 缺 member	`failed to load manifest for workspace member 'C:\qim\crates\qim-store'`	全部 crates（含 Cargo.toml）都要在

6. 本机（Windows VM）现状 —— 你只需跑最后两步¶

VM 已就绪： - ✅ Rust + Node + cargo-zigbuild + C:\zig-x86_64-windows-0.16.0 + C:\tools\protoc - ✅ 源码 C:\qim4\crates\qim-gui（含 node_modules，但需 Windows 重装） - ✅ C:\qim4\zigcc.bat（linker wrapper）

你跑（光驱 D:\ 上有 setup3.bat 已备好，或手动执行）：

:: 方式 A：运行光驱上的 setup3.bat（一键：重装 node_modules + tauri build）
D:\setup3.bat

:: 方式 B：手动
cd C:\qim4\crates\qim-gui
rmdir /s /q node_modules & npm install & npm run build
cd src-tauri
tauri build --no-bundle --target x86_64-pc-windows-gnu

构建完成后：

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

运行，gateway 填 192.168.122.1:7000（宿主管的 QIM 服务），登录后即可看到会话列表/聊天/群成员界面。