安装

快速安装（5 分钟）

bash

# 安装 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 安装程序并运行它。

验证安装：

PowerShell

go version  # 应显示 1.25 或更高版本

检查 PATH：

PowerShell

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

如果为空，请将 C:\Users\YourName\go\bin 添加到你的 PATH 中。

选项 1：官方安装程序

从 go.dev/dl 下载 macOS 安装程序 (.pkg 文件) 并运行它。

选项 2：Homebrew

bash

brew install go

验证安装：

bash

go version  # 应显示 1.25 或更高版本
echo $PATH | grep go/bin  # 应显示 ~/go/bin

如果 ~/go/bin 不在 PATH 中，请添加到 ~/.zshrc 或 ~/.bash_profile：

bash

export PATH=$PATH:~/go/bin

选项 1：官方压缩包

从 go.dev/dl 下载 Linux 压缩包，然后：

bash

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

选项 2：包管理器

bash

# Ubuntu/Debian
sudo apt install golang-go

# Fedora
sudo dnf install golang

# Arch
sudo pacman -S go

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

bash

export PATH=$PATH:/usr/local/go/bin:~/go/bin
source ~/.bashrc  # 重新加载

验证：

bash

go version
echo $PATH | grep go/bin

安装平台依赖项

WebView2 运行时（通常已预装）

Windows 10/11 默认包含 WebView2。如果缺失：
- 从 [Microsoft](https://developer.microsoft.com/microsoft-edge/webview2/) 下载
- 或者稍后运行 `wails3 doctor`——它将引导你完成

**就这样！** 不需要其他依赖项。

Xcode 命令行工具（必需）

bash

xcode-select --install

在出现的对话框中点击“安装”。

验证：

bash

xcode-select -p  # 应显示 /Library/Developer/CommandLineTools

就这样！ macOS 默认包含 WebKit。

构建工具和 WebKit

需要 Ubuntu 22.04+ 或 Debian 12+。

bash

sudo apt update
sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev

bash

sudo dnf install gcc pkg-config gtk3-devel webkit2gtk4.1-devel

bash

sudo pacman -S base-devel gtk3 webkit2gtk-4.1

bash

sudo zypper install gcc pkg-config gtk3-devel webkit2gtk3-devel

bash

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 CLI

bash

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

这将把 wails3 命令安装到 ~/go/bin（或在 Windows 上为 %USERPROFILE%\go\bin）。

验证安装

bash

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   | 已安装的版本 |
| 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 下载并运行安装程序。

验证：

PowerShell

npm --version

选项 1：官方安装程序 从 nodejs.org 下载

选项 2：Homebrew

bash

brew install node

验证：

bash

npm --version

选项 1：NodeSource

bash

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs  # Ubuntu/Debian

选项 2：包管理器

bash

sudo dnf install nodejs  # Fedora
sudo pacman -S nodejs npm  # Arch

验证：

bash

npm --version

故障排除

`wails3` 命令未找到

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

解决方案：

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

验证：

PowerShell

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

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

bash

export PATH=$PATH:~/go/bin

重新加载：

bash

source ~/.zshrc  # 或 ~/.bashrc

验证：

bash

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 工具：

bash

xcode-select --install

Go 版本过旧

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

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

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

bash

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

开发版本（最新开发版）

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

bash

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

下一步

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

构建你的第一个应用

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

第一个应用教程 →

探索模板

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

bash

wails3 init -l  # 列出模板

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

安装

快速安装（5 分钟）

逐步安装

安装 Go（必需）

安装平台依赖项

安装 Wails CLI

验证安装

安装 npm（可选但推荐）

故障排除

wails3 命令未找到

wails3 doctor 报告缺少依赖项

Go 版本过旧

开发版本（最新开发版）

下一步

`wails3` 命令未找到

`wails3 doctor` 报告缺少依赖项