# 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 作为验收路径 |