---
description: Windows 构建与打包规范：必须用 wails3 task，禁止裸 go build 出包
alwaysApply: true
---

# 构建与打包（Windows）

## 出包必须用官方任务，禁止裸 `go build`

```powershell
# ✅ 正确：产出 bin/code-count.exe（带图标、版本信息、无控制台窗口）
wails3 task windows:build

# ✅ 安装包（NSIS，内部会先执行上面的 build）
wails3 task 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` 前置检查），
产物不得交付给用户。

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