docs: add windows packaging verification

2026-07-09 01:20:36 +08:00
parent 7fbcd3a838
commit 07357c4766
6 changed files with 164 additions and 2 deletions
@@ -0,0 +1,125 @@
+# 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 已安装固定版本：
+
+   ```powershell
+   go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.9
+   $env:Path += ";$(go env GOPATH)\bin"
+   wails3 package -help
+   ```
+
+3. 前端依赖已安装：
+
+   ```powershell
+   cd frontend
+   npm install
+   cd ..
+   ```
+
+4. 默认 NSIS 打包需要 `makensis` 在 PATH 中：
+
+   ```powershell
+   Get-Command makensis
+   ```
+
+   如果找不到 `makensis`，先安装 NSIS，并把 NSIS 安装目录加入 PATH。
+
+5. Windows 打包资源存在：
+
+   ```text
+   build/windows/icon.ico
+   build/windows/info.json
+   build/windows/wails.exe.manifest
+   build/windows/nsis/project.nsi.tmpl
+   ```
+
+## 打包前验证
+
+打包前先确认普通构建通过：
+
+```powershell
+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，这是非阻塞提示。
+
+## 执行打包
+
+从项目根目录执行：
+
+```powershell
+$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`：
+
+```text
+-tags production -trimpath -buildvcs=false -ldflags="-w -s -H windowsgui"
+```
+
+## 输出目录
+
+普通构建输出：
+
+```text
+bin/cmbone.exe
+```
+
+默认 NSIS 安装包输出：
+
+```text
+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 作为验收路径 |