4. 环境准备：Go、Node 与平台依赖

本节目标

装对版本的 Go 和 Node，并把 Wails 命令行工具装上
按自己的系统补齐 WebView 相关的原生依赖
用 wails doctor 一次性验证环境是否达标
看懂得常见报错对应的缺哪一块

4-1 先装 Go

Wails 后端是 Go 写的，第一步得有 Go 工具链。v2.13.0 要求 Go 1.21 或更高。去 golang.org 下载对应系统的安装包，装完在终端确认版本：

go version
# 输出类似 go version go1.22.5 windows/amd64

如果你用的是比较新的系统，比如 macOS 15（Sequoia）及以上，官方建议 Go 升到 1.23.3 以上，否则编译时会踩到工具链的坑。不安心的话，直接装最新稳定版最省事。

Note

装完 Go 记得确认 GOPATH 的 bin 目录在 PATH 里。后面 go install 装的工具会落在这里，不在 PATH 的话命令行找不到它。一般 Go 默认就把 $GOPATH/bin 提示你了，自己 export 一下即可（Windows 在环境变量里加）。

4-2 再装 Node 和包管理器

前端部分要用 Node 构建。官方要求 Node 15 以上，实际用 LTS 版本（18 / 20 / 22）最稳，别用太老的。顺带确认 npm 也在：

node -v
npm -v

只装 Node 就够了，npm 自带。有些团队习惯 pnpm 或 yarn，Wails 不挑，模板里的构建命令本质都是调前端的打包脚本。

4-3 安装 Wails 命令行工具

Go 和 Node 就位后，装 Wails 自己的 CLI：

go install github.com/wailsapp/wails/v2/cmd/wails@latest

这条命令从官方仓库拉最新版（v2.13.0）并编译安装到 GOPATH/bin。装完敲：

wails version

能打印出版本号就说明 CLI 装好了。如果报”command not found”，八成是 4-1 里说的 PATH 没配，回去把 GOPATH/bin 加进环境变量，重开终端再试。

4-4 各平台的系统依赖

CLI 只是个壳，真正跑起来还要系统级的 WebView 和编译工具。这一块每个系统不一样，对号入座。

Windows。现代 Windows 10/11 大多自带 WebView2 运行时。你可以打开”设置 → 应用”搜 WebView2 确认，或者跑完 4-5 的 wails doctor 让它告诉你。万一没有（比如精简版系统），去微软官网下 WebView2 运行时装一下。Windows 这边一般不用额外装编译器，Go 自带。

macOS。需要 Xcode 命令行工具，提供编译用的 clang 等：

xcode-select --install

弹窗点安装即可。不需要完整 Xcode，命令行工具就够 Wails 用了。

Linux。依赖最多，主要是 GTK 和 WebKit 的开发库，外加 gcc 和 pkg-config。以 Debian/Ubuntu 系为例：

sudo apt install gcc libgtk-3-dev libwebkit2gtk-4.0-dev pkg-config

较新的发行版把 WebKit 升到了 4.1 系列，对应的是 libwebkit2gtk-4.1-dev，并且构建时要带 -tags webkit2_41。遇到 4.0 的包找不到就改用 4.1 那套，版本号对上就行。Arch、Fedora 的包名略有不同，但都是 gtk3 + webkit2gtk 这两个核心。

Warning

Linux 是三个平台里最容易卡在依赖上的。常见报错是编译时找不到 webkit2gtk-4.0 或 gtk+-3.0 的 .pc 文件。先确认 pkg-config 装了、上面的 -dev 包装全了，再清掉构建缓存重试。别急着怀疑代码，十有八九是系统库没齐。

4-5 用 wails doctor 验收

所有东西装完后，跑一个总检查：

wails doctor

它会逐项扫描：Go 版本、Node/npm 版本、各平台 WebView 依赖、Wails 本体版本，最后给一个清单，哪项是绿色 OK、哪项标红缺失。第一次跑建议认真读一遍输出，它能提前暴露你漏装的部件。

一个典型的达标输出里会看到类似这样的行：

System
------
OS:            Windows 11
Go Version:    go1.22.5
Node Version:  v20.11.0
npm Version:   v10.2.4

* Wails CLI:    v2.13.0
* WebView2:     Installed

只要关键项都是 OK，环境这一关就过了。

Tip

wails doctor 不只是安装时跑一次。以后遇到诡异的构建失败、WebVieW 相关报错，先跑它。它能区分”是我代码的问题”还是”环境缺东西”，省得你在代码里瞎改半天。

4-6 装好先验证，再往下走

环境搭完别急着进下一章，先用最短路径确认全链路是好的：临时建一个 wails init -n hellotest -t react-ts，进目录跑 wails dev，能看到窗口和模板界面就说明 Go、Node、WebView、CLI 四块都就位了。验证完用 Ctrl+C 关掉、把目录删掉，不留垃圾。

平时排错记住三个入口：go env GOPATH 看 Go 工作目录、npm config get prefix 看 npm 全局目录、wails doctor 看整体健康。命令行报找不到命令，基本都是这两个 PATH 没配，先确认再动手重装。

系统层面的坑也分阵营：Windows 优先查 WebView2 是否安装，macOS 优先确认 xcode-select --install 跑过，Linux 十有八九是 gtk3 或 webkit2gtk 的开发包装漏了。先定位自己卡在哪一环，再补对应依赖，别一上来就重装整套环境，那样既慢又容易把 PATH 搞乱。

4-7 不同系统的验证清单

装完环境建议按系统过一遍自检。Windows 上打开系统设置搜索 WebView2，能看到条目就说明运行时在位；再跑 wails doctor，WebView2 那行显示已安装即过关。macOS 打开终端敲命令查看命令行工具路径，能打印出来说明已装，若报找不到就重新执行安装。Linux 最麻烦，先确认编译器与 pkg-config 在，再确认 webkit 开发包在，最后 wails doctor 里 WebKit 相关项全绿。三系统都过了，环境这关才算真正踏实，后面写代码才不会被环境问题打断思路。每次重装系统或升级版本后，都值得重新跑一遍这个清单。

4-8 环境出问题先别急着重装

很多人环境一报红就删了重装，其实多半是 PATH 没配或某个开发包没齐。先跑 wails doctor 看具体缺哪一项，对症补齐比整体重装快得多，也避免把原本正常的配置搞乱。养成”先看报错、再动手”的习惯，能省下大把时间，也能让你更清楚每一块依赖到底在哪起作用。

常见误区

Go 装了但 wails 命令找不到。PATH 没包含 GOPATH/bin。这是新手最高频的问题，不是 Wails 没装上。

macOS 只装了完整 Xcode 却没跑 xcode-select --install。命令行工具没初始化时，Wails 调不到编译器。两者不是一回事，建议都确认一下。

Linux 用 root 装 WebKit 开发包后仍编译失败。可能是 pkg-config 路径或架构不匹配（比如 arm64 机器装了 amd64 的库）。wails doctor 的报错信息会指向具体缺的 .pc，照着补。

Node 用特别老的版本。低于 15 时前端模板的构建脚本可能跑不起来，直接升 LTS 省心。

小结

环境三件套：Go 1.21+、Node 15+（建议 LTS）、Wails CLI（go install ...@latest）。系统依赖按平台补——Windows 看 WebView2、macOS 跑 xcode-select --install、Linux 装 gcc + gtk3 + webkit2gtk 开发库。全部就位后用 wails doctor 验收，看到关键项全绿就能进下一章，正式 wails init 创建第一个应用。