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
@@ -69,6 +69,8 @@ Windows 下也可以直接运行：
 `dev.bat` 会从 `9245` 开始选择一个空闲 Vite 端口，避免已有 dev server 占用端口时无法打开 GUI。
 开发启动使用快速前端 dev 构建以尽快打开桌面窗口；提交前仍以 `npm run build` 做完整 TypeScript 检查和生产构建。

+Windows 打包验证见 [`docs/windows-packaging.md`](docs/windows-packaging.md)。当前默认打包路径是 NSIS，要求本机安装 `makensis`。
+
 ## Wails Bindings

 修改 Go 服务的公开方法、参数模型、返回模型，或在 `main.go` 注册新服务后，需要从项目根目录重新生成前端 bindings：
@@ -106,6 +108,7 @@ wails3 generate bindings -clean=true
 - [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：固定开工流程。
 - [`docs/current-state.md`](docs/current-state.md)：当前真实状态和命令。
 - [`docs/06-tasks.md`](docs/06-tasks.md)：任务看板。
+- [`docs/windows-packaging.md`](docs/windows-packaging.md)：Windows 打包验证流程。
 - [`progress.md`](progress.md)：执行流水和验证证据。

 统一验证入口：
@@ -107,6 +107,14 @@ Wails 构建：
 wails3 build
 ```

+Windows 打包：
+
+```powershell
+wails3 package
+```
+
+打包前置条件、输出目录和常见失败处理见 [`windows-packaging.md`](windows-packaging.md)。
+
 Windows 快捷脚本：

 ```powershell
@@ -48,7 +48,7 @@
 | --- | --- | --- | --- | --- |
 | T-030 | 建立常用组件示例页 | T-012 | 输入框、多选框、下拉框、多行文本、表格、筛选、分页、状态标签有可运行示例 | DONE |
 | T-031 | 文档化 Wails bindings 生成流程 | T-012 | README 或技术栈文档说明 `wails3 generate bindings` 的使用、失败处理和版本要求 | DONE |
-| T-032 | 补充 Windows 打包验证文档 | T-031 | `wails3 package` 前置条件、输出目录和常见失败处理写入 README 或 docs | TODO |
+| T-032 | 补充 Windows 打包验证文档 | T-031 | `wails3 package` 前置条件、输出目录和常见失败处理写入 README 或 docs | DONE |
 | T-033 | 完成一次模板 smoke 清单 | T-023 | 登录、设置、业务样例、日志、统计、组件示例、托盘、热键都按清单验证并记录结果 | TODO |
 | T-034 | 添加 Windows Wails 快捷脚本 | T-001 | `dev.bat` 一行切到项目根目录、补 Go bin PATH、自动选择空闲端口并运行 `wails3 dev`；`build.bat` 一行切到项目根目录、补 Go bin PATH 并运行 `wails3 build`；README、技术栈、当前状态和执行流水已同步 | DONE |

@@ -24,6 +24,7 @@
 - 前端框架：Vue 3、Vite、TypeScript、Tailwind CSS、Ant Design Vue
 - 当前 Wails 前端 bindings：由 `wails3 build` / `wails3 generate bindings` 生成的 `.js` 文件。
 - 已文档化 Wails bindings 生成流程：README 和技术栈文档包含固定版本、生成命令、失败处理和提交要求。
+- 已文档化 Windows 打包验证流程：`docs/windows-packaging.md` 包含 `wails3 package` 前置条件、NSIS 输出目录、验证清单和常见失败处理。
 - 本地数据库：SQLite，用户配置目录下 `cmbone/cmbone.db`
 - 当前本地演示账号：`admin` / `admin123`，密码由后端初始化为 salt + SHA-256 hash，不写死在前端。
 - 当前主窗口路由：`/#/` 重定向到 `/#/dashboard`。
@@ -85,6 +86,8 @@ wails3 build
 - OCR 和热键依赖平台实现，跨平台修改需要分别验证。
 - 当前前端以构建检查为主，暂未引入专门的前端单元测试。
 - bindings 生成依赖本机安装的 `wails3`。
+- Windows 默认打包路径依赖 NSIS `makensis`；当前本机 PATH 未检测到 `makensis`。
+- 当前项目未配置 `wails.json`，MSIX 暂不作为可用打包路径。
 - `npm install` 当前报告 3 个 moderate audit findings，后续如做依赖治理应单独开任务。
 - 前端构建当前有 Browserslist 数据过期和 chunk 大小警告，不阻塞生产构建。
 - Windows 快捷脚本依赖 `go env GOPATH` 下的 `bin\wails3.exe`，如果未安装 Wails CLI，先按 README 安装固定版本。
@@ -219,9 +222,16 @@ wails3 build
 - 明确固定版本：Go `1.23.0`、Wails CLI `v3.0.0-alpha.9`、`@wailsio/runtime 3.0.0-alpha.66`。
 - 明确生成命令、生成时机、常见失败处理、提交要求和验证命令。

+同日完成 Windows 打包验证文档：
+
+- 新增 `docs/windows-packaging.md`。
+- README 和技术栈文档已链接该文档。
+- 文档记录 `wails3 package` 前置条件、默认 NSIS 路径、输出目录、安装包验证清单和常见失败处理。
+- 已确认本机 `wails3 package -help` 可用，但 PATH 中未检测到 `makensis`，因此未强跑 NSIS 打包。
+
 ## 下一步

-从 [`06-tasks.md`](06-tasks.md) 领取第一个 `TODO` 任务。目前建议先做 `T-032`：补充 Windows 打包验证文档。
+从 [`06-tasks.md`](06-tasks.md) 领取第一个 `TODO` 任务。目前建议先做 `T-033`：完成一次模板 smoke 清单。

 ## 当前 blocker

@@ -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 作为验收路径 |
@@ -353,3 +353,19 @@
  - `git diff --check` 通过。
 - 非阻塞警告：
  - 文档任务未改运行代码，未重复执行构建。
+
+### 补充 Windows 打包验证文档
+
+- 任务：完成 `T-032`，`wails3 package` 前置条件、输出目录和常见失败处理写入 README 或 docs。
+- 结果：
+  - 新增 `docs/windows-packaging.md`。
+  - README 和 `docs/03-tech-stack.md` 已链接 Windows 打包验证文档。
+  - 文档明确默认 NSIS 打包路径、`makensis` 前置条件、`bin/cmbone-amd64-installer.exe` 输出目录、安装包验证清单和常见失败处理。
+  - 文档明确当前项目没有 `wails.json`，MSIX 暂不作为验收路径。
+- 验证：
+  - `$env:Path += ";$(go env GOPATH)\bin"; wails3 package -help` 通过。
+  - `Get-Command makensis` 未找到命令，已写入文档风险。
+  - `git diff --check` 通过。
+- 非阻塞警告：
+  - 文档任务未改运行代码。
+  - 本机缺少 NSIS `makensis`，未强跑 `wails3 package`。