설치
빠른 설치 (5분)
단계별 설치
Go 설치 (필수)
Wails는 Go 1.25 이상이 필요합니다.
go.dev/dl 에서 Windows 설치 프로그램을 다운로드하여 실행하세요.
설치 확인:
go version # 1.25 이상이어야 함
PATH 확인:
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
결과가 비어 있다면, C:\Users\YourName\go\bin을 PATH에 추가하세요.
옵션 1: 공식 설치 프로그램
go.dev/dl 에서 macOS 설치 프로그램(.pkg 파일)을 다운로드하여 실행하세요.
옵션 2: Homebrew
brew install go
설치 확인:
go version # 1.25 이상이어야 함
echo $PATH | grep go/bin # ~/go/bin이 표시되어야 함
~/go/bin이 PATH에 없다면, ~/.zshrc 또는 ~/.bash_profile에 추가하세요:
export PATH=$PATH:~/go/bin
옵션 1: 공식 Tarball
go.dev/dl 에서 Linux tarball을 다운로드한 후:
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.linux-amd64.tar.gz
옵션 2: 패키지 관리자
# Ubuntu/Debian
sudo apt install golang-go
# Fedora
sudo dnf install golang
# Arch
sudo pacman -S go
PATH에 추가 (~/.bashrc 또는 ~/.zshrc에 추가):
export PATH=$PATH:/usr/local/go/bin:~/go/bin
source ~/.bashrc # 다시 로드
확인:
go version
echo $PATH | grep go/bin
플랫폼 종속성 설치
WebView2 런타임 (일반적으로 사전 설치됨)
Windows 10/11에는 WebView2가 기본적으로 포함되어 있습니다. 누락된 경우:
- [Microsoft](https://developer.microsoft.com/microsoft-edge/webview2/)에서 다운로드
- 또는 나중에 `wails3 doctor`를 실행하면 안내에 따라 설치할 수 있습니다.
**이것으로 끝!** 다른 종속성은 필요하지 않습니다.
Xcode 명령줄 도구 (필수)
xcode-select --install
나타나는 대화 상자에서 “Install"을 클릭하세요.
확인:
xcode-select -p # /Library/Developer/CommandLineTools가 표시되어야 함
이것으로 끝! macOS에는 WebKit가 기본적으로 포함되어 있습니다.
빌드 도구 및 WebKit
Ubuntu 22.04+ 또는 Debian 12+가 필요합니다.
sudo apt update
sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
sudo dnf install gcc pkg-config gtk3-devel webkit2gtk4.1-devel
sudo pacman -S base-devel gtk3 webkit2gtk-4.1
sudo zypper install gcc pkg-config gtk3-devel webkit2gtk3-devel
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 설치
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 | 설치된 버전 |
| 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을 사용합니다.
옵션 1: NodeSource
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs # Ubuntu/Debian
옵션 2: 패키지 관리자
sudo dnf install nodejs # Fedora
sudo pacman -S nodejs npm # Arch
확인:
npm --version
문제 해결
wails3 명령을 찾을 수 없음
원인: ~/go/bin(또는 Windows의 %USERPROFILE%\go\bin)이 PATH에 없습니다.
해결 방법:
- “환경 변수"를 엽니다(시작 메뉴에서 검색)
- “사용자 변수"에서
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를 찾을 수 없음
설치 명령: sudo apt install libwebkit2gtk-4.1-devWindows: WebView2가 없는 경우:
- Microsoft에서 다운로드
- 또는 첫 번째 앱 실행 시 자동으로 설치됩니다
macOS: Xcode 도구가 없는 경우:
xcode-select --install
Go 버전이 너무 오래됨
Wails v3에는 Go 1.25+가 필요합니다. 이전 버전이 있는 경우:
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
개발 버전 (Bleeding Edge)
최신 개발 브랜치에서 가장 최신 코드를 사용하고 싶으신가요? 이를 통해 릴리스되기 전에 새로운 기능과 수정 사항을 사용할 수 있지만, 버그와 중단 변경(breaking changes)의 위험이 따릅니다. 기여자나 다가오는 기능을 테스트해야 하는 사람에게만 권장됩니다.
git clone https://github.com/wailsapp/wails.git
cd wails
git checkout v3
cd v3/cmd/wails3
go install
다음 단계
설치 완료! 시스템이 Wails 개발을 위해 준비되었습니다.
10분 안에 작동하는 애플리케이션을 만드세요.
기본으로 제공되는 항목을 확인하세요.
wails3 init -l # 템플릿 목록