安装 · Wails

快速安装（5 分钟）

bash

# Install Go 1.25+, then:
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
wails3 setup   # Interactive setup wizard (experimental)

也可以使用wails3 doctor手动验证。跳转到第一个应用 →

分步安装

安装 Go（必需）

Wails 需要 Go 1.25或更高版本。

从go.dev/dl下载 Windows 安装程序并运行。

验证安装：

PowerShell

go version  # Should show 1.25 or later

检查 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  # Should show 1.25 or later
echo $PATH | grep go/bin  # Should show ~/go/bin

如果 PATH 中没有~/go/bin，请将其添加到~/.zshrc或~/.bash_profile：

bash

export PATH=$PATH:~/go/bin

选项1：官方 Tar 包

从go.dev/dl下载 Linux tar 包，然后执行：

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  # Reload

验证：

bash

go version
echo $PATH | grep go/bin

安装平台依赖项

WebView2 Runtime（通常已预装）

Windows 10/11默认包含 WebView2。如果缺失：

从Microsoft下载
也可以稍后运行wails3 doctor，它会提供引导

就这么简单！无需其他依赖项。

Xcode Command Line Tools（必需）

bash

xcode-select --install

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

验证：

bash

xcode-select -p  # Should show /Library/Developer/CommandLineTools

就这么简单！macOS 默认包含 WebKit。

构建工具和 WebKit

默认 GTK4 技术栈要求 Ubuntu 24.04或更高版本，或者 Debian 13或更高版本。

bash

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

bash

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

bash

sudo pacman -S base-devel gtk4 webkitgtk-6.0

bash

sudo zypper install gcc pkg-config gtk4-devel webkitgtk-6_0-devel

bash

sudo emerge --ask net-libs/webkit-gtk:6

添加到shell.nix或devShell：

nix

buildInputs = with pkgs; [ webkitgtk_6_0 gtk4 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 setup

设置向导会检查依赖项，帮助安装缺失的依赖项，并配置项目默认设置。

验证安装

bash

wails3 doctor

预期输出（或类似内容）：

text

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   | Your installed version |
| Go Version  | go1.25.0        |
└─────────────┴─────────────────┘

# 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  # or ~/.bashrc

验证：

bash

echo $PATH | grep go/bin
wails3 version

`wails3 doctor`报告缺少依赖项

Linux：输出会明确告知你需要安装哪些软件包。例如：

text

❌ 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

开发版本（最前沿版本）

想使用主开发分支中的绝对最新代码？这样可以在新功能和修复正式发布前使用它们，但也有遇到错误和破坏性变更的风险。仅建议贡献者或需要测试即将推出功能的用户使用。

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  # List templates

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

无障碍

编辑此文档

安装

快速安装（5 分钟）

分步安装

安装 Go（必需）

安装平台依赖项

安装 Wails CLI

运行设置向导（推荐）

验证安装

安装 npm（可选但推荐）

故障排除

找不到`wails3`命令

`wails3 doctor`报告缺少依赖项

Go 版本过旧

开发版本（最前沿版本）

后续步骤

快速安装（5 分钟）

分步安装

安装 Go（必需）

安装平台依赖项

安装 Wails CLI

运行设置向导（推荐）

验证安装

安装 npm（可选但推荐）

故障排除

找不到wails3命令

wails3 doctor报告缺少依赖项

Go 版本过旧

开发版本（最前沿版本）

后续步骤

找不到`wails3`命令

`wails3 doctor`报告缺少依赖项