33. wails build 命令详解

本节目标

搞清楚一条 wails build 背后到底跑了哪几步
掌握日常最常用的七八个参数，知道什么场景该加什么
会用 -debug、-dryrun 定位构建期和运行期的问题
分清哪些参数是 Windows 专属，哪些三端通用
明白命令行参数和 wails.json 谁覆盖谁

33-1 一条命令背后的五个阶段

wails build 看着简单，内部是一条流水线。按顺序是这五步：

安装前端依赖（读 wails.json 里的 frontend:install）
构建前端项目（读 frontend:build）
生成构建资源（图标、Windows 清单文件等）
编译 Go 应用（把前端产物 embed 进去）
可选的压缩步骤（-upx）

知道这个顺序，很多参数的作用就好理解了。比如 -s 是「跳过前端构建」，它砍掉的就是第 1、2 两步；-nopackage 砍掉第 3 步；-upx 打开第 5 步。

编译 Go 那一步，Wails 默认带了这些参数：

go build -tags desktop,production -ldflags "-w -s"

Windows 上 ldflags 会额外加 -H windowsgui，作用是不弹黑色控制台窗口。-w -s 是去掉调试信息和符号表，能显著减小体积。

Note

你通过 -tags 和 -ldflags 传进来的值是追加到默认值后面，不是替换。所以不用担心写了自己的 tag 就丢掉 desktop,production。

33-2 日常最常用的几个参数

-platform 指定目标平台

wails build -platform windows/amd64
wails build -platform darwin/universal

取值表在第 32 章列过了。逗号分隔可以一次编多个，但只能是同一操作系统的不同架构。

-o 指定输出文件名

wails build -o MyApp.exe

不加这个参数时，文件名取 wails.json 里的 outputfilename；那里也没配，就用项目名。

-clean 清空 build/bin

wails build -clean

它会删掉 build/bin 目录再重建。发布构建建议都加上，避免上一次残留的旧文件混进产物。日常开发不用加，多花时间。

-s 跳过前端构建

wails build -s

只改了 Go 代码、前端一行没动时，加上它能省掉一次完整的 Vite 打包。大项目上这个时间差很可观。

Warning

-s 的前提是 frontend/dist 里已经有一份可用的产物。第一次构建或者刚 -clean 过就直接加 -s，会 embed 到空目录，跑起来是白屏。

-upx 压缩二进制

wails build -upx
wails build -upx -upxflags "--best --lzma"

UPX 是个可执行文件压缩工具，能把体积压掉一半以上。用之前得先自己装 UPX。

Warning

两个坑要提前知道。一是 Windows 上部分杀毒软件会把 UPX 压缩过的程序误报成病毒；二是 Apple Silicon 上 UPX 有已知问题，压出来的程序可能跑不起来。对外分发前一定在目标机器上实测。

-tags 传 Go 构建标签

wails build -tags "webkit2_41"
wails build -tags "prod,nosqlite"

值必须加引号，多个标签用空格或逗号分隔，但别混着用。Linux 下选 WebKit ABI 版本就靠它，第 36 章会细说。

-obfuscated 混淆构建

wails build -obfuscated

用 garble 对 Go 代码做混淆，配套的 -garbleargs 可以调混淆策略。第 37 章专门讲这个。

33-3 调试与诊断相关的参数

-debug：保留调试信息，并在应用里打开开发者工具。这是排查「开发模式好好的、构建完就出问题」的主力手段。

wails build -debug

用 -debug 编出来的程序，运行方式和正式版一致，但可以右键打开 DevTools 看控制台和网络请求。定位完记得重新编一版不带 -debug 的再发出去。

-devtools：只开开发者工具，不保留调试信息。正式构建（没加 -debug）时用它，可以用 Ctrl/Cmd+Shift+F12 唤起 DevTools。

Warning

官方明确说明：带 -devtools 的包会通不过 Mac App Store 审核。这个开关只用于内部调试版本。

-dryrun：只打印将要执行的构建命令，不真的执行。想知道 Wails 到底拼了一条什么样的 go build，用它一看便知。

wails build -dryrun

-race：开启 Go 的竞态检测器。后端有并发逻辑、怀疑有数据竞争时用。它会明显拖慢程序，只在排查阶段用。

-v：日志详细程度，取值 0（静默）、1（默认）、2（详细）。CI 上出问题看不清原因，加 -v 2。

33-4 Windows 专属的几个开关

这三个参数在别的平台上没有意义。

-nsis：生成 NSIS 安装程序。

wails build -nsis

需要先装好 NSIS，产物同样落在 build/bin。第 34 章讲配置细节。

-webview2：WebView2 运行时的处理策略，四选一——download、embed、browser、error，默认 download。

wails build -webview2 embed

这决定了用户机器上没有 WebView2 时，你的程序怎么办。同样放在第 34 章展开。

-windowsconsole：保留控制台窗口。默认构建会加 -H windowsgui 隐藏控制台，加上这个参数就不隐藏了。做命令行辅助工具或者想看 fmt.Println 输出时有用。

33-5 完整参数速查

上面挑的是高频项，这里补齐剩下的，用到时回来查。

参数	作用	默认值
`-clean`	清空 `build/bin` 目录
`-compiler "compiler"`	换一个 Go 编译器	`go`
`-debug`	保留调试信息并开启 DevTools
`-devtools`	仅在正式构建中开启 DevTools
`-dryrun`	只打印构建命令不执行
`-f`	强制构建
`-garbleargs`	传给 garble 的参数	`-literals -tiny -seed=random`
`-ldflags "flags"`	追加 ldflags
`-m`	编译前跳过 `go mod tidy`
`-nopackage`	不打包应用（跳过图标、清单生成）
`-nocolour`	关闭彩色输出
`-nosyncgomod`	不把 `go.mod` 同步到 Wails 版本
`-nsis`	生成 NSIS 安装包（Windows）
`-o filename`	输出文件名
`-obfuscated`	用 garble 混淆
`-platform`	目标平台，逗号分隔	构建机的 GOOS/GOARCH
`-race`	开启竞态检测
`-s`	跳过前端构建
`-skipbindings`	跳过绑定生成
`-skipembedcreate`	不自动创建缺失的 embed 目录
`-tags "extra tags"`	追加构建标签，需加引号
`-trimpath`	从产物中去掉文件系统路径
`-u`	把项目 `go.mod` 更新到 CLI 同版本
`-upx`	用 UPX 压缩
`-upxflags`	传给 UPX 的参数
`-v int`	日志级别 0/1/2	1
`-webview2`	WebView2 策略（Windows）	`download`
`-windowsconsole`	保留控制台窗口（Windows）

-trimpath 顺带说一句：它把编译机的绝对路径从二进制里抹掉。既减小体积，也避免把 /Users/你的名字/项目/ 这种路径泄露给用户。对外分发建议加上。

33-6 命令行参数与 wails.json 的关系

有些配置两个地方都能写，规则是命令行参数优先。

wails.json 里能持久化的构建相关字段主要有这些：

{
  "name": "myapp",
  "outputfilename": "MyApp",
  "build:tags": "webkit2_41",
  "obfuscated": "true",
  "garbleargs": "-literals -tiny -seed=random",
  "nsisType": "multiple",
  "frontend:install": "npm install",
  "frontend:build": "npm run build"
}

build:tags 的值会在所有构建里生效，不用每次敲 -tags。obfuscated 和 garbleargs 同理，团队里统一好之后写进配置文件，谁构建都一致。

Tip

一个实用习惯：把团队约定的固定项（输出名、构建标签、混淆策略）写进 wails.json，把因人因场景而异的项（-clean、-debug、-platform）留在命令行。这样新人克隆下来直接 wails build 就能得到正确产物。

macOS 上还有一个环境变量可以调最低系统版本：

CGO_CFLAGS=-mmacosx-version-min=10.15.0 \
CGO_LDFLAGS=-mmacosx-version-min=10.15.0 \
wails build

需要兼容更老的 macOS 时用得上。

常见误区

把 -s 当成通用加速开关。 它只在前端确实没变时才安全。CI 里千万别加，第一次构建就会出白屏。

以为 -tags 会覆盖默认标签。 它是追加。反过来说，如果你真想去掉 desktop,production，wails build 做不到，得走第 38 章的手动构建。

发布版忘了去掉 -debug。 带调试信息的包体积更大，还把 DevTools 暴露给了用户。发版前检查一遍构建命令。

混淆标志名记混。 官方文档正文里出现过 -obfuscate 的说法，但实际命令和参数表用的是 -obfuscated，带 d。敲错了 CLI 会报未知参数。

小结

wails build 的参数不少，但真正天天用的就那么几个：-platform 选目标、-o 定名字、-clean 保干净、-s 抢时间、-upx 减体积。

调试三件套是 -debug、-devtools、-dryrun，分别对应「构建产物有 bug」「正式包要临时看控制台」「想知道命令怎么拼的」。

固定配置往 wails.json 里放，可变项留给命令行——这个分工能让团队协作省掉一大堆口头约定。

接下来三章按平台走，先从 Windows 的打包和安装程序开始。