설치
Wails를 설치하고 애플리케이션 빌드 준비하기
빠른 설치(5분)
단계별 설치
Go 설치(필수)
Wails에는 Go 1.25 이상이 필요합니다.
go.dev/dl에서 Windows 설치 프로그램을 다운로드하여 실행하세요.
설치 확인:
go version # Should show 1.25 or later
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 # Should show 1.25 or later
echo $PATH | grep go/bin # Should show ~/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 # Reload
확인:
go version
echo $PATH | grep go/bin
플랫폼 종속 항목 설치
WebView2 Runtime(대개 사전 설치됨)
Windows 10/11에는 기본적으로 WebView2가 포함되어 있습니다. 없는 경우:
- Microsoft에서 다운로드하세요.
- 또는 나중에
wails3 doctor을 실행하면 안내를 받을 수 있습니다.
이것으로 끝입니다! 다른 종속 항목은 필요하지 않습니다.
Xcode Command Line Tools(필수)
xcode-select --install
표시되는 대화 상자에서 “Install"을 클릭하세요.
확인:
xcode-select -p # Should show /Library/Developer/CommandLineTools
이것으로 끝입니다! macOS에는 기본적으로 WebKit이 포함되어 있습니다.
빌드 도구 및 WebKit
기본 GTK4 스택을 사용하려면 Ubuntu 24.04 이상 또는 Debian 13 이상이 필요합니다.
sudo apt update
sudo apt install build-essential pkg-config libgtk-4-dev libwebkitgtk-6.0-dev
sudo dnf install gcc pkg-config gtk4-devel webkitgtk6.0-devel
sudo pacman -S base-devel gtk4 webkitgtk-6.0
sudo zypper install gcc pkg-config gtk4-devel webkitgtk-6_0-devel
sudo emerge --ask net-libs/webkit-gtk:6
shell.nix 또는 devShell에 추가하세요:
buildInputs = with pkgs; [ webkitgtk_6_0 gtk4 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 setup
설정 마법사는 종속 항목을 확인하고, 누락된 항목의 설치를 도우며, 프로젝트 기본값을 구성합니다.
설치 확인
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 | 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을 사용합니다.
옵션 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(또는 %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 # or ~/.bashrc
확인:
echo $PATH | grep go/bin
wails3 version
wails3 doctor에서 누락된 종속성을 보고함
Linux: 출력에 설치해야 할 패키지가 정확히 표시됩니다. 예:
❌ webkit2gtk not found
Install with: 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
개발 버전(최신 개발판)
주 개발 브랜치의 가장 최신 코드를 사용하고 싶으신가요? 릴리스 전에 새로운 기능과 수정 사항을 사용할 수 있지만, 버그와 호환성을 깨는 변경 사항이 포함될 위험이 있습니다. 기여자 또는 출시 예정 기능을 테스트해야 하는 사용자에게만 권장합니다.
git clone https://github.com/wailsapp/wails.git
cd wails
git checkout v3
cd v3/cmd/wails3
go install
다음 단계
설치가 완료되었습니다! 이제 시스템에서 Wails 개발을 시작할 수 있습니다.
10분 만에 작동하는 애플리케이션을 만드세요.
기본으로 제공되는 항목을 확인하세요.
wails3 init -l # List templates