7. wails.json 配置全字段

本节目标

看懂 wails.json 里每个字段控制什么
会改前端目录、构建输出、dev 服务器等关键项
知道构建钩子和混淆参数怎么写
拿到一份能直接照着改的示例配置

7-1 这个文件管什么

wails.json 是 Wails 项目的”工程配置”，管的是 构建流程层面 的事：前端目录在哪、构建产物叫什么、dev 时怎么起前端服务器、构建前后跑什么脚本。注意它和 main.go 里的 options.App 分工不同——options.App 管运行时行为（窗口、绑定、生命周期），wails.json 管命令行怎么把项目编出来。两者别搞混。

Note

有些旧资料里会提 backend、assetstype、bindings 这类字段。在 v2.13.0 里，后端固定是 Go，前端资源默认走 Go 的 //go:embed 嵌入，不需要在 wails.json 里配置嵌入策略，所以这些字段你已经看不到了。下面只讲当前真实存在的字段。

7-2 一份完整示例

先给一份接近真实项目的配置，后面逐行拆：

{
  "version": 2,
  "name": "myapp",
  "assetdir": "frontend/dist",
  "reloaddirs": "public,assets",
  "build:dir": "build",
  "build:tags": "",
  "frontend:dir": "frontend",
  "frontend:install": "npm install",
  "frontend:build": "npm run build",
  "frontend:dev:watcher": "npm run dev",
  "frontend:dev:serverUrl": "",
  "frontend:dev:wailsjsdir": "src",
  "wailsjsdir": "frontend/src",
  "viteServerTimeout": 10,
  "outputfilename": "mytool",
  "debounceMS": 100,
  "appargs": "",
  "nsisType": "user",
  "obfuscated": false,
  "garbleargs": ""
}

7-3 基础与资源字段

version：配置文件格式版本号，当前是 2。Wails 据此决定怎么解析这份配置，别手改成别的数。

name：应用名。默认用作窗口标题和产物名，也出现在安装包信息里。

assetdir：前端构建产物的目录，wails build 时从这里取 index.html 和资源嵌进二进制。默认 frontend/dist，也就是 Vite 的默认输出目录。你换了打包工具、输出目录不同，就改这里。

reloaddirs：dev 模式下除了前端目录，还要监听哪些目录的变化来触发重载。比如你把图片、模板放在 public、assets 目录，前端构建不管它们，就得列在这里，否则改了不会热更新。多个目录用英文逗号隔开。

outputfilename：最终二进制文件的名字。不填就用 name。想让 exe 叫 mytool.exe 而不是 myapp.exe，在这里定。

7-4 构建与前端字段

build:dir：构建产物的输出目录，默认 build。wails build 出来的二进制落在 build/bin/ 下。

build:tags：传给 Go 编译器的 build tags。比如 Linux 新 WebKit 要带 webkit2_41，写在这里就省得每次命令行加 -tags。多个 tag 用空格隔开。

frontend:dir：前端工程根目录，默认 frontend。

frontend:install：dev/build 前装依赖的命令，默认 npm install。你用 pnpm 就改成 pnpm install。

frontend:build：构建前端的命令，默认 npm run build。

frontend:dev:watcher：dev 模式下跑的前端监视命令，默认 npm run dev，负责热重载。

frontend:dev:serverUrl：当你不用 Vite、而是自带外部 dev server（比如 Create React App）时，把它填成那个 server 的地址（如 http://localhost:3000），Wails 就不自己起 Vite，而是连过去。Vite 模板下留空即可。

frontend:dev:wailsjsdir 和 wailsjsdir：生成绑定文件（wailsjs）放哪。frontend:dev:wailsjsdir 是新字段，填相对于 frontend:dir 的路径（如 src）；wailsjsdir 是老写法，填完整路径。两者指向同一个地方，新项目用前者就行。

viteServerTimeout：dev 时 Wails 等 Vite 服务器就绪的最长秒数，默认 10。前端工程大、起得慢就调大，免得 Wails 等不及报错。

7-5 dev 与产物细节字段

debounceMS：dev 模式下 Go 文件变动的防抖毫秒数，默认 100。连保存时避免反复重编。

appargs：wails dev 启动应用时额外传给程序的命令行参数。调试”启动时接收参数”这类功能时用得上。

nsisType：Windows NSIS 安装包的生成方式，只有两个取值——multiple 表示每个目标架构各出一个安装包，single 表示所有参与构建的架构合成一个通用安装包。不填默认 multiple。打包章会再展开。

7-6 高级字段：钩子与混淆

preBuildHooks / postBuildHooks：构建前/后跑的脚本，按平台写。比如构建前自动生成版本号文件，构建后自动压缩。格式是对象，键是平台（windows/darwin/linux/all），值是命令：

{
  "preBuildHooks": {
    "all": "echo 开始构建",
    "windows": "powershell -command \"Write-Host win\""
  },
  "postBuildHooks": {
    "all": "echo 构建完成"
  }
}

runNonNativeBuildHooks：是否允许在非目标平台跑构建钩子。默认 false，跨平台构建时钩子不会乱跑；需要强制跑就设 true。

obfuscated：是否用 garble 混淆 Go 代码，true/false。开启后增加反编译难度，但构建会慢、且可能影响调试。

garbleargs：传给 garble 的额外参数，配合 obfuscated 使用，比如控制混淆强度。

Warning

obfuscated 开启后，出错时的堆栈会很难读，排问题很痛苦。除非你要发布对外产品、在意代码被轻易反编译，否则开发期保持 false。混淆的详细玩法后面有专门一章。

7-7 info 字段与改配置不生效的排查

wails.json 里还有一组 info 字段，用来填作者、版本、描述这类元信息，会进到安装包的属性详情里，建议填上方便用户查看。另外注意 version 是配置格式版本（当前是 2），别和你的应用版本号搞混，两者不是一回事。

改了 wails.json 却发现没生效，按这三处查：第一，字段名拼错或层级写错（比如把 frontend:build 写成 build:frontend），Wails 会静默忽略不认识的键；第二，assetdir 改了但 main.go 的 //go:embed 路径没跟着改，取到的还是旧目录；第三，误以为运行时行为能靠 wails.json 改——窗口大小、置顶这些是 options.App 管的，改 wails.json 没用。定位不清时就看 wails dev / wails build 启动时终端打印的配置解析日志，Wails 会输出它实际读到的关键项。

7-8 改完配置记得重跑

wails.json 的修改不需要手动重启什么服务，下一次 wails dev 或 wails build 会自动重新读取。但如果你改的是影响路径或构建输出的字段，建议顺手清一下 build 目录再编，避免新旧产物混在一起让你误判。配置这种事，宁可多确认一次，少背一次锅。

另外，wails.json 是给 Wails 命令行读的，不是给 Go 编译器读的。它不参与 //go:embed 的编译期嵌入，只影响”怎么把项目编出来”。这个边界清楚了，你就不会在两者间来回猜”为什么改了没用”。

常见误区

改了 wails.json 的 assetdir 却忘了改 //go:embed 路径。wails.json 告诉 Wails 去哪取前端文件，而 main.go 里的 //go:embed all:frontend/dist 决定编译时嵌哪个目录。两边路径要对上，否则要么取不到文件，要么嵌了旧目录。

把运行时配置写进 wails.json。窗口大小、是否置顶、绑定哪些方法，这些是 options.App 的事，不在 wails.json。wails.json 只管”怎么编出来”。

frontend:dev:serverUrl 乱填。Vite 模板下留空就好；填错地址会导致 dev 模式连不上前端，窗口白屏。只有用非 Vite 的前端框架才需要它。

小结

wails.json 管构建流程：name/outputfilename 定名字，assetdir/frontend:dir 定目录，build:tags 传编译标签，frontend:dev:serverUrl 接外部 dev server，debounceMS/appargs 调 dev 行为，preBuildHooks/postBuildHooks 挂脚本，obfuscated/garbleargs 做混淆。记住它和 options.App 的分工——前者管”怎么编”，后者管”运行时什么样”。下一章就讲 options.App 这个运行时配置大本营。