安裝

快速安裝（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 Runtime（通常已預先安裝）

Windows 10/11 預設包含 WebView2。如果遺漏：
- 從 [Microsoft](https://developer.microsoft.com/microsoft-edge/webview2/) 下載
- 或稍後執行 `wails3 doctor`——它會引導你完成

**就這些！** 不需要其他相依套件。

Xcode Command Line Tools（必要）

bash

xcode-select --install

在出現的對話框中點擊「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（Windows 上為 %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
   安裝方式：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

開發版本（Bleeding Edge）

想要使用來自主要開發分支的最新程式碼嗎？這讓您可以提前體驗新功能與修復，但也伴隨著錯誤與破壞性變更的風險。僅建議貢獻者或需要測試即將推出功能的人使用。

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 版本過舊

開發版本（Bleeding Edge）

下一步

找不到 `wails3` 命令

`wails3 doctor` 回報缺少依賴項