安裝 · 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

如果 ~/go/bin 不在 PATH 中，請將它加入 ~/.zshrc 或 ~/.bash_profile：

bash

export PATH=$PATH:~/go/bin

選項 1：官方 Tarball

從 go.dev/dl 下載 Linux tarball，然後執行：

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中提問，或建立問題回報。

無障礙功能

編輯此文件

安裝

快速安裝（5 分鐘）

逐步安裝

安裝 Go（必要）

安裝平台相依套件

安裝 Wails CLI

執行設定精靈（建議）

驗證安裝

安裝 npm（選用但建議）

疑難排解

找不到`wails3`命令

`wails3 doctor`回報缺少相依套件

Go 版本過舊

開發版本（最前沿版本）

後續步驟

快速安裝（5 分鐘）

逐步安裝

安裝 Go（必要）

安裝平台相依套件

安裝 Wails CLI

執行設定精靈（建議）

驗證安裝

安裝 npm（選用但建議）

疑難排解

找不到wails3命令

wails3 doctor回報缺少相依套件

Go 版本過舊

開發版本（最前沿版本）

後續步驟

找不到`wails3`命令

`wails3 doctor`回報缺少相依套件