安装

快速安装（5 分钟）

# 安装 Go 1.25+，然后：
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
wails3 doctor  # 验证安装

如果 wails3 doctor 通过，则安装完成。跳转到第一个应用 →

逐步安装

安装 Go（必需）

Wails 需要 Go 1.25 或更高版本。
从 go.dev/dl 下载 Windows 安装程序并运行它。
验证安装：
Terminal window
go version # 应显示 1.25 或更高版本
检查 PATH：
Terminal window
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
如果为空，请将 C:\Users\YourName\go\bin 添加到你的 PATH 中。
选项 1：官方安装程序
从 go.dev/dl 下载 macOS 安装程序 (.pkg 文件) 并运行它。
选项 2：Homebrew
Terminal window
brew install go
验证安装：
Terminal window
go version # 应显示 1.25 或更高版本 echo $PATH | grep go/bin # 应显示 ~/go/bin
如果 ~/go/bin 不在 PATH 中，请添加到 ~/.zshrc 或 ~/.bash_profile：
Terminal window
export PATH=$PATH:~/go/bin
选项 1：官方压缩包
从 go.dev/dl 下载 Linux 压缩包，然后：
Terminal window
sudo rm -rf /usr/local/go sudo tar -C /usr/local -xzf go1.25.linux-amd64.tar.gz
选项 2：包管理器
Terminal window
# Ubuntu/Debian sudo apt install golang-go # Fedora sudo dnf install golang # Arch sudo pacman -S go
添加到 PATH（添加到 ~/.bashrc 或 ~/.zshrc）：
Terminal window
export PATH=$PATH:/usr/local/go/bin:~/go/bin source ~/.bashrc # 重新加载
验证：
Terminal window
go version echo $PATH | grep go/bin
安装平台依赖项
WebView2 运行时（通常已预装）
Windows 10/11 默认包含 WebView2。如果缺失：
- 从 Microsoft 下载
- 或者稍后运行 wails3 doctor——它将引导你完成
就这样！ 不需要其他依赖项。
考虑使用 Dev Drive 存储你的项目。Dev Drives 针对开发者工作负载进行了优化，可以将构建时间和磁盘访问速度提高多达 30%。
Xcode 命令行工具（必需）
Terminal window
xcode-select --install
在出现的对话框中点击“安装”。
验证：
Terminal window
xcode-select -p # 应显示 /Library/Developer/CommandLineTools
就这样！ macOS 默认包含 WebKit。
构建工具和 WebKit
Wails v3 需要 WebKitGTK 4.1（使用 libsoup3）。仅提供 4.0 的旧发行版——Ubuntu 20.04、Debian 11、RHEL 8/9 及其衍生版本——不受支持。
Ubuntu/Debian
Fedora
Arch
openSUSE
Gentoo
NixOS
其他
需要 Ubuntu 22.04+ 或 Debian 12+。
Terminal window
sudo apt update sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
Terminal window
sudo dnf install gcc pkg-config gtk3-devel webkit2gtk4.1-devel
Terminal window
sudo pacman -S base-devel gtk3 webkit2gtk-4.1
Terminal window
sudo zypper install gcc pkg-config gtk3-devel webkit2gtk3-devel
Terminal window
sudo emerge --ask net-libs/webkit-gtk:4.1
添加到你的 shell.nix 或 devShell：
buildInputs = with pkgs; [ webkitgtk_4_1 gtk3 pkg-config gcc ];
安装 Wails 后运行 wails3 doctor——它将显示你的发行版所需的确切软件包。
Wails 还提供实验性的 GTK4 / WebKitGTK 6.0 支持。如果你想使用 GTK4 构建，请为你的发行版安装额外的依赖项，并使用 wails3 build -tags gtk4 进行构建。有关详细信息，请参阅 Linux 打包 - GTK4。
安装 Wails CLI
Terminal window
```
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
```
这将把 wails3 命令安装到 ~/go/bin（或在 Windows 上为 %USERPROFILE%\go\bin）。

验证安装

wails3 doctor

预期输出（或类似）：

Wails (v3.0.0-dev)  Wails Doctor

# System

┌──────────────────────────────────────────────────┐
| Name          | MacOS                            |
| Version       | 26.0                             |
| ID            | 25A354                           |
| Branding      | MacOS 26.0                       |
| Platform      | darwin                           |
| Architecture  | arm64                            |
| Apple Silicon | true                             |
| CPU           | Apple M2 Pro                     |
| CPU 1         | Apple M2 Pro                     |
| CPU 2         | Apple M2 Pro                     |
| GPU           | 16 cores, Metal Support: Metal 4 |
| Memory        | 16 GB                            |
└──────────────────────────────────────────────────┘

# Build Environment

┌─────────────┬─────────────────┐
| Wails CLI   | v3.0.0-alpha.40 |
| Go Version  | go1.24.6        |
└─────────────┴─────────────────┘

# Dependencies

┌─────────────────┬─────────────────────────────────────────────────┐
| npm             | 11.6.2                                          |
| *NSIS           | Not Installed. Install with `brew install...`.  |
| Xcode cli tools | 2412                                            |
└─────────────────┴─────────────────────────────────────────────────┘

# Checking for issues

SUCCESS No issues found

# Diagnosis

SUCCESS Your system is ready for Wails development!

安装 npm（可选但推荐）

大多数 Wails 模板使用 npm 进行前端工具链管理。
从 nodejs.org 下载并运行安装程序。
验证：
Terminal window
npm --version
选项 1：官方安装程序 从 nodejs.org 下载
选项 2：Homebrew
Terminal window
brew install node
验证：
Terminal window
npm --version
选项 1：NodeSource
Terminal window
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs # Ubuntu/Debian
选项 2：包管理器
Terminal window
sudo dnf install nodejs # Fedora sudo pacman -S nodejs npm # Arch
验证：
Terminal window
npm --version
更喜欢 pnpm、yarn 或 bun？没问题！只需更新项目中的 Taskfile.yml 使用你偏好的工具即可。

故障排除

`wails3` 命令未找到

原因： ~/go/bin（或 %USERPROFILE%\go\bin）不在 PATH 中。

解决方案：

Windows
macOS/Linux

打开”环境变量”（在开始菜单中搜索）
在”用户变量”下，找到 Path
点击”编辑”→“新建”
添加：C:\Users\YourName\go\bin（将 YourName 替换为你的用户名）
点击所有对话框中的”确定”
重启终端

验证：

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

添加到 ~/.zshrc（macOS）或 ~/.bashrc（Linux）：

export PATH=$PATH:~/go/bin

重新加载：

source ~/.zshrc  # 或 ~/.bashrc

验证：

echo $PATH | grep go/bin
wails3 version

`wails3 doctor` 报告缺少依赖项

Linux： 输出会告诉你需要安装哪些软件包。示例：

❌ webkit2gtk not found
   Install with: sudo apt install libwebkit2gtk-4.1-dev

Windows： 如果缺少 WebView2：

从 Microsoft 下载
或者运行你的第一个应用时会自动安装

macOS： 如果缺少 Xcode 工具：

xcode-select --install

Go 版本过旧

Wails v3 需要 Go 1.25+。如果你使用的是旧版本：

Windows/macOS
Linux

从 go.dev/dl 下载最新版本并重新安装。

从 go.dev/dl 下载最新的 tarball，然后执行：

sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.linux-amd64.tar.gz

开发版本（最新开发版）

想要使用主开发分支中的最新代码吗？这让你能在正式发布前访问新功能和修复，但也伴随着 bug 和破坏性更改的风险。仅推荐给贡献者或需要测试即将推出功能的人员。

git clone https://github.com/wailsapp/wails.git
cd wails
git checkout v3
cd v3/cmd/wails3
go install

下一步

安装完成！ 你的系统已准备好进行 Wails 开发。

构建你的第一个应用

在 10 分钟内创建一个可用的应用程序。

第一个应用教程 →

探索模板

查看开箱即用的可用内容。

wails3 init -l  # 列出模板

遇到问题？ 请在 Discord 提问或提交 issue。

安装