126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# 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 作为验收路径 |
|