---
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 并嵌入，无需手动。