난독화 빌드

Garble은 go build을 대체하여 심볼 이름을 변경하고, 상수를 난독화하며, 생성된 바이너리에서 디버그 정보를 제거하는 Go 빌드 도구입니다. Wails v3에서는 두 가지 새로운 명령을 통해 Garble을 기본 지원합니다.

사전 요구 사항

• Go 1.26.2 이상 — Garble v0.16.0에 필요합니다.
• Garble v0.16.0

go install mvdan.cc/garble@v0.16.0

필수: 서비스 타입에 JSON 태그 추가하기

바인딩된 서비스 메서드가 반환하거나 인수로 받는 모든 구조체에는 내보낸 각 필드에 명시적인 JSON 태그가 있어야 합니다.

// Without tags — breaks under Garble
type OrderSummary struct {
    ID        int
    Total     float64
    LineItems []LineItem
}

// With tags — safe under Garble
type OrderSummary struct {
    ID        int       `json:"id"`
    Total     float64   `json:"total"`
    LineItems []LineItem `json:"lineItems"`
}

Wails 자체 타입인 Screen, Rect, Point, Size, EnvironmentInfo, OSInfo, Capabilities에는 이미 태그가 지정되어 있습니다. 직접 정의한 타입에만 태그를 지정하면 됩니다.

난독화하여 빌드하기

wails3 generate bindings -obfuscated

wails3 build --obfuscated

Garble에 추가 플래그 전달하기

옵션을 garble에 직접 전달하려면 --garbleargs을 사용하세요.

# Obfuscate string literals and reduce binary size
wails3 build --obfuscated --garbleargs "-literals -tiny"

# Reproducible output — same seed produces the same binary
wails3 build --obfuscated --garbleargs "-seed=deadbeef"

지원되는 플래그의 전체 목록은 Garble 문서를 참조하세요.

고급: ID 파일을 다른 패키지에 쓰기

기본적으로 wails_obfuscated.gen.go은 main 패키지와 같은 위치에 기록됩니다. 프로젝트에서 서비스를 main이 가져오는 하위 패키지에 두는 경우에는 -obfuscated-output을 사용하여 파일을 해당 위치에 기록할 수 있습니다.

wails3 generate bindings -obfuscated -obfuscated-output ./internal/services

문제 해결

garble: command not found

Garble이 설치되어 있지 않거나 $(go env GOPATH)/bin이 PATH에 없습니다.

go install mvdan.cc/garble@v0.16.0
export PATH="$PATH:$(go env GOPATH)/bin"

프런트엔드가 잘못되거나 비어 있는 필드 값을 받음

서비스 반환 타입에 json:"..." 태그가 없습니다. 바인딩된 메서드가 반환하는 모든 구조체를 확인하고 내보낸 각 필드에 명시적인 태그를 추가하세요.

브라우저 콘솔의 binding not found 오류

안정적인 ID 파일이 없거나 컴파일에 포함되지 않았습니다. 다음을 확인하세요.

• main 패키지 디렉터리(또는 -obfuscated-output에 전달한 디렉터리)에 wails_obfuscated.gen.go이 있는지 확인하세요.
• wails_obfuscated 빌드 태그를 추가하는 wails3 build --obfuscated을 실행했는지 확인하세요.
• -obfuscated-output을 사용했다면 대상 패키지를 main에서 가져오는지 확인하세요.

Windows Defender가 빌드를 바이러스로 탐지함

Garble로 난독화된 Go 바이너리는 디버그 심볼이 없고 패킹된 실행 파일과 유사하므로 빌드 중 Windows Defender가 휴리스틱 방식으로 탐지합니다. 빌드는 다음 오류와 함께 실패합니다.

open C:\Users\...\AppData\Local\Temp\go-build...\a.out.exe: The file contains a virus or potentially unwanted software.

임시 디렉터리(Go가 중간 빌드 아티팩트를 기록하는 위치)와 프로젝트 디렉터리를 Defender의 제외 목록에 추가하세요.

Add-MpPreference -ExclusionPath "$env:TEMP"
Add-MpPreference -ExclusionPath "C:\path\to\your\project"

이러한 제외 설정은 지정된 경로에만 적용되며 Defender를 시스템 전체에서 비활성화하지 않습니다.

unsupported Go version 오류로 빌드 실패

Garble v0.16.0에는 Go 1.26.2 이상이 필요합니다. Go를 업그레이드하거나 Garble 릴리스 페이지에서 사용 중인 툴체인과 호환되는 버전을 확인하세요.