72 lines
3.0 KiB
Plaintext
72 lines
3.0 KiB
Plaintext
---
|
||
description: Windows 构建与打包规范：必须用 wails3 task，禁止裸 go build 出包
|
||
alwaysApply: true
|
||
---
|
||
|
||
# 构建与打包（Windows）
|
||
|
||
## 出包必须用官方任务，禁止裸 `go build`
|
||
|
||
```powershell
|
||
# ✅ 正确：产出 bin/code-count.exe（带图标、版本信息、无控制台窗口）
|
||
wails3 task windows:build
|
||
|
||
# ✅ 安装包（NSIS；先 api:package，再 windows:build + makensis）
|
||
# 若报 makensis not found，把 NSIS 加入 PATH 后再跑，例如：
|
||
# $env:Path = "C:\Program Files (x86)\NSIS;" + $env:Path
|
||
wails3 task package
|
||
|
||
# ✅ 仅打包后端（有改动才重编；强制：wails3 task api:package FORCE=1）
|
||
wails3 task api:package
|
||
|
||
# ❌ 错误：裸 go build 出的 exe 没有图标、双击会闪控制台黑框
|
||
go build -o bin/code-count.exe .
|
||
```
|
||
|
||
原因:图标不是自动带上的。官方任务先执行 `wails3 generate syso`,把
|
||
`build/windows/icon.ico` + `build/windows/info.json`(版本信息) +
|
||
`wails.exe.manifest` 编成 `wails_windows_amd64.syso` 链接进 exe,
|
||
构建完会删除 `*.syso`,所以仓库里平时看不到这个文件。
|
||
production 构建还带 `-tags production -ldflags "-w -s -H windowsgui"`。
|
||
|
||
裸 `go build` 仅可用于快速验证编译通过（如 `go vet` / `go test` 前置检查），
|
||
产物不得交付给用户。
|
||
|
||
## 后端一并打包（必须是 linux/amd64）
|
||
|
||
`wails3 task package` 会先跑 `api:package`：检测同级目录 `../nl-pms-api` 源码指纹，
|
||
有改动才交叉编译到 `bin/nl-pms-api/`，并带上 `init.sql`、`migrations/*.sql`、
|
||
`config.example.yaml`。部署服务器时拷该目录即可。
|
||
|
||
### 硬性要求（打包后必须核对）
|
||
|
||
- 目标平台固定为 **`GOOS=linux` + `GOARCH=amd64`**（线上 Linux 服务器用）。
|
||
- 产物路径：`bin/nl-pms-api/nl-pms-api`（**无** `.exe` 后缀）。
|
||
- **禁止**把 Windows 本机 `go build` 出的 `nl-pms-api.exe` 当作后端交付物。
|
||
- 脚本 `tools/package-api.ps1` 编完后会校验文件头为 ELF（`7F 45 4C 46`）；不是 ELF 则失败。
|
||
- 人工抽查（可选）：
|
||
|
||
```powershell
|
||
# 应为 ELF 64-bit LSB executable, x86-64
|
||
Format-Hex bin\nl-pms-api\nl-pms-api -Count 4
|
||
# 前 4 字节应为 7F 45 4C 46
|
||
```
|
||
|
||
单独只打后端：`wails3 task api:package`；强制重编：`wails3 task api:package FORCE=1`。
|
||
|
||
## 换 logo 的流程
|
||
|
||
1. 替换 `build/appicon.png`（源头，正方形 PNG）。
|
||
2. 跑 `wails3 task common:generate:icons` 重新生成 `build/windows/icon.ico`
|
||
与 `build/darwin/icons.icns`（该任务按 appicon.png 的 checksum 缓存，
|
||
没改动会显示 up to date）。
|
||
3. 重新 `wails3 task windows:build`。
|
||
4. 验证：`powershell -ExecutionPolicy Bypass -File tools\extract-icon.ps1`
|
||
会从 exe 提取图标存成 `tools/exe-icon-check.png`，肉眼确认。
|
||
5. 资源管理器仍显示旧图标属 Windows 图标缓存问题，改名或重启 explorer 即可。
|
||
|
||
## 开发运行
|
||
|
||
- 热更开发：`wails3 dev -config ./build/config.yml -port 9245`（即 `wails3 task dev`）。
|
||
- 只改前端时，`wails3 task windows:build` 会自动 npm build 并嵌入，无需手动。
|