Wails v3 环境安装

发表于 更新于 分类于
从零搭建 Wails v3 桌面开发环境：Go、NSIS、平台依赖、CLI 安装与 wails3 doctor 自检。

前言

Wails v3 是用 Go 编写后端、用系统 WebView 渲染前端的桌面应用框架，相比 Electron 体积更小、启动更快。
当前 v3 仍处于 Alpha 阶段，CLI 命令为 wails3（与 v2 的 wails 不同），安装链路与平台依赖也有变化。
本文按顺序说明：安装 Go、配置 PATH、各平台系统依赖、NSIS（Windows 安装包）、安装 CLI、运行配置向导与自检。
下文以官方文档为准，版本号请按你本机 wails3 doctor 输出核对。

依赖

Wails v3 至少需要 Go；前端模板通常还会用到 npm，建议一并安装。
若要打出 Windows 安装包（.exe 安装程序），还需安装 NSIS。

Go

官方要求 Go 1.24 及以上（Quick Start 页面建议 1.25+）。
可从 go.dev/dl 下载安装包，macOS 也可使用 .pkg 安装器。

安装完成后，在终端执行下面命令确认版本。

1
go version

Go 通过 go install 安装的工具会放到 $GOPATH/bin（默认 ~/go/bin），需要把该目录加入 PATH，否则会出现 wails3: command not found。

macOS 默认 Shell 为 Zsh，编辑 ~/.zshrc 并追加 PATH（Bash 用户改为 ~/.bash_profile）。

1
export PATH="$HOME/go/bin:$PATH"

保存后让配置生效。

1
source ~/.zshrc

也可参考本站 Go 环境安装 一文配置代理与 GOPATH。

npm

多数 Wails 模板使用 npm 管理前端依赖，属于可选项但强烈建议安装。
可从 nodejs.org 安装 LTS 版本，或用 nvm 管理多版本 Node。

安装后执行下面命令确认。

1
2
node -v
npm -v

NSIS

NSIS（Nullsoft Scriptable Install System）用于生成 Windows 安装程序。
Wails v3 在 wails3 package 打包 Windows 目标时会调用 makensis 编译 build/windows/nsis/ 下的脚本。
日常 wails3 dev 开发不依赖 NSIS；仅在需要分发 Windows 安装包，或在 macOS / Linux 上交叉打包 Windows 安装包时才需安装。

wails3 doctor 会检测 NSIS 是否可用，未安装时会给出对应平台的安装提示。

Windows

可用包管理器安装，装好后一般会自动加入 PATH。

Winget（Windows 10+ 推荐）：

1
winget install NSIS.NSIS --silent

Scoop：

1
2
scoop bucket add extras
scoop install nsis

Chocolatey：

1
choco install nsis

若从 NSIS 官网 手动安装，需把安装目录下的 Bin 文件夹（内含 makensis.exe）加入系统 Path，然后重开终端。

安装完成后验证：

1
makensis /VERSION

能输出版本号即表示可用。

macOS

Homebrew 提供 makensis formula（别名 nsis），一条命令即可安装。

1
brew install makensis

验证：

1
makensis -VERSION

Linux

多数发行版可通过包管理器安装，包名通常为 nsis。

Debian / Ubuntu：

1
sudo apt install nsis

Fedora / RHEL：

1
sudo dnf install nsis

Arch Linux：

1
sudo pacman -S nsis

验证：

1
makensis -VERSION

在 Linux 上交叉打出 Windows 安装包时，除 NSIS 外还需能构建 Windows 二进制（如 wails3 build GOOS=windows），具体以项目 build/ 下 Taskfile 为准。

实现

支持平台

Wails v3 官方列出的支持平台如下（其它 Linux 发行版也可能可用，但需自行验证依赖包名）。

  • Windows 10/11（AMD64 / ARM64）
  • macOS 10.15+（Intel）/ macOS 11.0+（Apple Silicon）
  • Ubuntu 24.04（AMD64 / ARM64）

Windows

Windows 上主要依赖 WebView2 运行时。
Windows 10/11 通常已预装；若缺失，可从 Microsoft WebView2 下载安装包。

除 Go 与 PATH 外，Windows 一般不需要额外安装 GTK 等 Linux 专用库。
安装 CLI 后可用 wails3 doctor 检查 WebView2 是否就绪。

若 go\bin 未加入 PATH，可在「环境变量」的用户 Path 中新建一项，例如 C:\Users\你的用户名\go\bin，保存后重开终端。

PowerShell 中可用来检查 go\bin 是否在 PATH 里。

1
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }

macOS

macOS 需要安装 Xcode Command Line Tools，其中包含编译 Wails 所需的工具链。

在终端执行下面命令，按提示完成安装。

1
xcode-select --install

安装完成后可验证路径是否可用。

1
xcode-select -p

能输出类似 /Library/Developer/CommandLineTools 的路径即表示正常。
macOS 使用系统 WebKit 作为 WebView，无需像 Linux 那样单独安装 WebKitGTK 开发包。

Linux

Linux 上安装 wails3 CLI 时会编译 CGO 代码，必须先安装对应开发库，否则 go install 会报 pkg-config 找不到 gtk / webkit 的错误。

v3 默认使用 GTK4 + WebKitGTK 6.0 栈（Ubuntu 24.04+、Debian 13+ 等较新发行版）。
若你仍在 Ubuntu 22.04、Debian 12 等仅提供 GTK3 的环境上开发，可改用 legacy 构建标签 -tags gtk3（计划在 v3.1 移除）。

Debian / Ubuntu（默认 GTK4 栈）：

下面命令安装编译工具链与 GTK4 / WebKitGTK 6.0 开发包。

1
2
sudo apt update
sudo apt install build-essential pkg-config libgtk-4-dev libwebkitgtk-6.0-dev

Debian / Ubuntu（legacy GTK3 栈，仅旧发行版需要）：

1
sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev

Fedora / RHEL：

1
sudo dnf install gcc pkg-config gtk4-devel webkitgtk6.0-devel

legacy 路径：

1
sudo dnf install gtk3-devel webkit2gtk4.1-devel

Arch Linux：

1
sudo pacman -S base-devel gtk4 webkitgtk-6.0

legacy 路径：

1
sudo pacman -S gtk3 webkit2gtk-4.1

安装 CLI

环境就绪后，用 go install 安装 Wails v3 命令行工具。
安装产物为 wails3，位于 ~/go/bin/wails3。

1
go install -v github.com/wailsapp/wails/v3/cmd/wails3@latest

验证 CLI 是否可用。

1
wails3 version

若提示命令不存在，请确认 ~/go/bin 已加入 PATH 并已重开终端。

配置向导

官方推荐首次安装后运行交互式配置向导 wails3 setup。
向导会检查平台依赖、协助安装缺失项，并可配置作者信息、Bundle ID 前缀、Docker 交叉编译与代码签名等默认值。

1
wails3 setup

若向导在你的系统上无法正常运行，可改用手动安装平台依赖，再执行下文「验证」中的 wails3 doctor。

开发版 CLI

如需跟踪 v3 分支最新代码（可能不稳定），可从源码安装 CLI。
生成的项目会通过 Go replace 指向开发版 Wails。

1
2
3
4
5
git clone https://github.com/wailsapp/wails.git
cd wails
git checkout v3
cd v3/cmd/wails3
go install

验证

wails3 doctor 会汇总系统信息、Go 版本、npm、NSIS 与平台依赖，并给出修复建议。
安装或排错时都应优先跑一遍。

1
wails3 doctor

输出末尾出现 SUCCESS 或「ready for Wails development」类提示，即表示环境基本可用。

可再创建一个最小项目做冒烟测试（需已安装 npm）。

1
2
3
wails3 init -n myapp -t vanilla
cd myapp
wails3 dev

能弹出窗口并热重载，说明开发链完整。

若需验证 Windows 安装包流程，在项目目录执行（需已安装 NSIS）：

1
wails3 package GOOS=windows

产物通常位于 build/bin 目录。

列出可用模板：

1
wails3 init -l

扩展

命令找不到

现象： 终端提示 wails3: command not found。

原因： go install 把二进制装在 ~/go/bin，但该目录不在 PATH 中。

处理： 按上文「依赖 → Go」将 $HOME/go/bin 加入 PATH，保存配置后关闭并重开终端，再执行 which wails3。

Go 版本过旧

现象： wails3 doctor 或编译时报 Go 版本不满足要求。

处理： 从 go.dev/dl 安装 1.24+（建议 1.25+），安装后重新打开终端并执行 go version 确认。

Linux 缺少 webkit

现象： go install 失败，或 wails3 doctor 提示 webkitgtk-6.0 / webkit2gtk 未找到。

处理： 按 wails3 doctor 给出的 apt / dnf / pacman 建议安装对应 -dev 包。
默认路径安装 GTK4 栈；旧发行版若只有 GTK3，安装 legacy 包并在构建时加 -tags gtk3。

Windows 缺少 WebView2

现象： 运行应用时 WebView 无法加载。

处理： 安装 WebView2 运行时，或先运行一次 wails3 dev，部分环境下会自动引导安装。

macOS 缺少 Xcode 工具

现象： 编译报错找不到 clang 或 SDK。

处理： 执行 xcode-select --install 完成 Command Line Tools 安装；若已安装仍报错，可执行 sudo xcode-select --reset 后重试。

缺少 NSIS

现象： wails3 doctor 提示 NSIS 未安装，或 wails3 package GOOS=windows 报错找不到 makensis。

处理： 按上文「依赖 → NSIS」在对应平台安装，并确认 makensis 在 PATH 中。
Windows 手动安装时务必把 NSIS 的 Bin 目录加入 Path；macOS 可用 brew install makensis。
安装后重开终端，再执行 wails3 doctor 确认 NSIS 项为已安装。

总结

  1. 安装 Go 1.24+（建议 1.25+），并把 ~/go/bin 加入 PATH。
  2. 按平台安装依赖：Windows 关注 WebView2；macOS 安装 Xcode CLT；Linux 安装 GTK4 / WebKitGTK 6.0 开发包（旧系统可用 -tags gtk3）。
  3. 执行 go install github.com/wailsapp/wails/v3/cmd/wails3@latest 安装 CLI。
  4. 运行 wails3 setup（可选）与 wails3 doctor 完成自检。
  5. 建议安装 npm，便于使用官方前端模板与 wails3 dev 热重载。
  6. 需要 Windows 安装包时安装 NSIS，并用 wails3 package GOOS=windows 验证。

v3 仍在快速迭代，遇到文档与本地行为不一致时，以 wails3 doctor 输出与 v3.wails.io 为准。