cmbone/docs/windows-packaging.md

Windows 打包验证

本文记录当前项目在 Windows 10+ 上执行 wails3 package 前需要确认的条件、默认输出位置和常见失败处理。

当前范围

• 默认打包格式：NSIS 安装包。
• 当前 Wails CLI：wails3 v3.0.0-alpha.9。
• 当前项目没有 wails.json，MSIX 任务暂不作为可用路径。
• Windows 打包配置位于 build/windows/。

前置条件

1. Go、Node.js、npm 可用。

2. Wails CLI 已安装固定版本：

   go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.9
   $env:Path += ";$(go env GOPATH)\bin"
   wails3 package -help
   

3. 前端依赖已安装：

   cd frontend
   npm install
   cd ..
   

4. 默认 NSIS 打包需要 makensis 在 PATH 中：

   Get-Command makensis
   

   如果找不到 makensis，先安装 NSIS，并把 NSIS 安装目录加入 PATH。

5. Windows 打包资源存在：

   build/windows/icon.ico
   build/windows/info.json
   build/windows/wails.exe.manifest
   build/windows/nsis/project.nsi.tmpl
   

打包前验证

打包前先确认普通构建通过：

go test ./...
cd frontend
npm run build
cd ..
go build -o bin\cmbone.exe .
cmd /c build.bat

build.bat 使用 wails3 build，会生成 bin\cmbone.exe。当前 Wails v3 alpha CLI 会提示 wails3 build 是 wails3 task 的 alias，这是非阻塞提示。

执行打包

从项目根目录执行：

$env:Path += ";$(go env GOPATH)\bin"
wails3 package

当前 Taskfile 的 Windows package 会走 NSIS：

1. 先执行 production build。
2. 生成 WebView2 bootstrapper。
3. 调用 makensis 生成安装包。

Production build 使用的关键参数来自 build/windows/Taskfile.yml：

-tags production -trimpath -buildvcs=false -ldflags="-w -s -H windowsgui"

输出目录

普通构建输出：

bin/cmbone.exe

默认 NSIS 安装包输出：

bin/cmbone-amd64-installer.exe

该路径来自 build/windows/nsis/project.nsi.tmpl 的 OutFile 配置。

MSIX 不是当前默认路径。build/windows/Taskfile.yml 中的 MSIX task 依赖 wails.json，但当前项目根目录没有该文件；需要后续单独配置后再启用。

安装包验证

生成安装包后至少检查：

1. bin/cmbone-amd64-installer.exe 存在且文件大小不为 0。
2. 在 Windows 10+ 测试机或虚拟机运行安装包。
3. 安装完成后桌面和开始菜单快捷方式可启动应用。
4. 主窗口可见，默认进入 /#/dashboard。
5. 本地演示账号 admin / admin123 可登录。
6. 能打开 /#/image-optimizer、/#/settings、/#/components。
7. 卸载入口可用，卸载后安装目录被移除。

常见失败

现象	处理
wails3 找不到	安装固定版本，并把 $(go env GOPATH)\bin 加入当前 PowerShell PATH
makensis 找不到	安装 NSIS，把 NSIS 目录加入 PATH 后重新打开终端
WebView2 bootstrapper 生成失败	检查网络、代理和杀毒软件拦截；必要时单独执行 wails3 generate webview2bootstrapper -dir build/windows/nsis
前端构建失败	先运行 cd frontend && npm install && npm run build，修复 TypeScript 或依赖问题
bindings 失效	运行 wails3 generate bindings -clean=true，再运行 npm run build
Go 编译失败	运行 go test ./... 和 go build -o bin\cmbone.exe . 定位服务或模型错误
图标、manifest 或版本信息错误	检查 build/windows/icon.ico、build/windows/wails.exe.manifest、build/windows/info.json
MSIX 打包失败	当前项目未配置 wails.json，不要把 MSIX 作为验收路径