6. 开发模式与构建

本节目标

搞懂 wails dev 在背后做了哪几件事
会用浏览器 devtools 调试前端界面
分清开发模式和生产构建在前端资源上的差别
用 wails build -platform 打出别的系统的包

6-1 开发模式 wails dev

日常写代码，绝大多数时间泡在 wails dev 里：

wails dev

它一次性做齐这几件事：

扫描 Bind 里的 Go 结构体，生成/刷新 frontend/wailsjs/ 下的绑定文件。
启动 Vite 开发服务器，监听 frontend/ 下的源码变化，前端改了即时热重载。
把前端请求接到 Vite 服务器，同时把 Go 编译进应用并跑起来，打开桌面窗口。
监听 .go 文件变化，Go 侧改了自动重新编译重启。

也就是说，前端热重载、Go 重编译、绑定刷新，一条命令全包了。你只管改代码看效果。

Tip

改 Go 代码时，Wails 对文件变动有个默认的防抖（debounce，默认 100ms），避免保存瞬间的连续触发导致反复重编。觉得反应慢可以调小，但别设成 0，连续保存会让你编译个不停。

6-2 用浏览器调试界面

桌面程序最不方便的就是”没法按 F12 看元素”。Wails 给了一个很实用的办法：

wails dev -browser

这个参数会在应用启动的同时，用你的默认浏览器打开一个调试地址（默认 http://localhost:34115）。在浏览器里你能用完整的 devtools：看元素、看网络、打前端断点、看 console。前端的改动在浏览器和桌面窗口里同步热重载，调试体验跟写网页一模一样。

为什么能这样？因为开发模式下，界面其实是从 Vite 开发服务器加载的，浏览器访问的是同一份资源。等到了生产构建，资源被嵌进二进制，就不需要这个服务器了。

Note

浏览器里调界面方便，但浏览器环境不等于 WebView 环境。最终用户在 WebView 里跑，个别 CSS 或 API 表现可能有差异。界面调得差不多了，记得回桌面窗口再目视确认一遍。

6-3 开发模式 vs 生产构建

这是新人最容易混淆的点，把两边的前端资源来源讲清楚：

开发模式。前端资源来自 Vite 开发服务器，支持热重载、source map、未压缩代码。Wails 会把 /wails/ipc.js 和 /wails/runtime.js 注入到页面，前者是桥的 JS 端，后者是运行时 API（事件、对话框等）。这两个脚本在开发时由 Wails 实时提供。

生产构建。前端先 npm run build 打成静态文件，再由 //go:embed 编进二进制。运行时 WebView 直接从 embed.FS 读 index.html 和资源，不再有 Vite 服务器，也不再有热重载。绑定的 wailsjs 同样重新生成一次，确保和生产代码一致。

一句话：开发时”活”的资源从服务器来、方便调；生产时”死”的资源在二进制里、方便发。

6-4 生产构建 wails build

代码写定、要出包了，用：

wails build

产物落在 build/bin/ 下，是一个独立的二进制（Windows 是 exe）。它已经把前端资源嵌进去了，拷到同系统的干净机器上双击就能跑（前提是那台机器有对应 WebView 运行时，见第 4 章）。

常用几个参数：

# 先清掉旧构建再编，避免缓存作怪
wails build -clean

# 带调试符号，方便出问题时定位（也能在窗口里开 devtools）
wails build -debug

# 指定输出文件名
wails build -o mytool

# 给 Go 编译传额外 build tags（如 Linux 新版 webkit）
wails build -tags webkit2_41

Warning

-debug 编出来的包体积更大、且能开 devtools，只适合自己排查问题，不要拿去分发。正式发布用不带 -debug 的普通构建。

6-5 跨平台构建 -platform

在一台机器上打别的系统的包，靠 -platform：

# 在 macOS 上打通用的 Apple 芯片 + Intel 包
wails build -platform darwin/universal

# 打 Windows 64 位
wails build -platform windows/amd64

# 打 Linux 64 位
wails build -platform linux/amd64

格式是 系统/架构。跨平台编译有几个前提：Go 原生支持交叉编译大部分组合，但前端依赖的系统库要目标平台有。最典型的坑在 Linux：打 Linux 包必须在 Linux 环境（或有对应 webkit 开发库的交叉工具链）里做，而且新版本 WebKit 要带 -tags webkit2_41。Windows 和 macOS 的包也各自最好在对应宿主上打，跨系统打安装包（NSIS、dmg）尤其如此。

Tip

现实里别指望”一台 Windows 机器打出三个平台的完美安装包”。常规做法是：各自平台跑 CI 构建，或者就在对应系统上分别 wails build。跨平台编译适合出二进制草稿，出正式安装包还是回到目标系统更稳。

6-6 开发模式的实用附加参数

除了 -browser，wails dev 还有几个日常好用的开关。-appargs 给应用传启动参数，调试”启动时读命令行”功能时必备；-debounce 改 Go 文件变动的防抖毫秒数，机器慢就调大避免频繁重编；-forcebuild 强制重新构建前端，缓存抽风时救命；-noreload 关掉前端自动重载，只保留 Go 重编译，排查重载引发的怪问题时用；-tags 在 dev 时也传 Go build tags，和 wails build 保持一致。

这些参数和 wails.json 里的对应字段是同一回事：命令行写的优先级更高，没写就取 wails.json。理解这一点，你就知道配置该放文件还是放命令行——团队共享的放 wails.json，临时调试的放命令行，互不打扰。

常见误区

以为 wails dev 卡住不动了。有时 Vite 在后台编译，终端看着静默，其实窗口已经在加载。等几秒，或看终端有没有报错，别急着 Ctrl+C。

在 dev 里测好就直接发，忘了 build。dev 模式资源从服务器来，build 才验证”嵌进二进制能不能跑”。发布前务必跑一次 wails build 实测。

跨平台构建报错就怪 Wails。大多不是框架问题，是目标系统的 webkit/gtk 库没装、或 build tags 没对。Linux 包打不出来，先回第 4 章把那几个 -dev 包装全。

小结

wails dev 管开发：生成绑定、起 Vite 热重载、Go 改了重编译，加 -browser 能用浏览器 devtools 调界面；开发时资源来自服务器，生产时来自二进制。wails build 管出包：产物在 build/bin/，-clean 清缓存、-debug 带调试、-platform 跨平台编。记住”dev 调、build 发”，以及跨平台包最好在目标系统上打，这两点就够应付日常了。下一章深入 wails.json 的每个配置字段。