지난 6개월여간 여러 Go Wails 앱을 제작하면서 경험한 운영체제별 문제점 해결에 관한 글입니다.

노하우라는게 그렇듯.. 누군게에는 도움이 될수도 있지만, 잘아는 사람들에게 잘못된 내용이 많을수도 있을것입니다.

아직 언노운하우 부분이 많으니까요. 하하.. 부족한 점은 댓글로 달아주시면 많은 Go Wails 제작자에게 도움이 될것입니다!

주로 AI가 알아듣기 좋게 작성되어 있습니다.

🚀 Wails 크로스 플랫폼 앱 제작 가이드

이 가이드는 Wails를 사용하여 Windows, macOS, Linux 환경에서 일관된 사용자 경험을 제공하고, 특히 macOS의 네이티브 기능을 완벽하게 지원하기 위한 공통 지침을 담고 있습니다.

📂 1. 프로젝트 구조 및 코드 표준

코드 관리 및 아키텍처

• 파일 위치: 새롭게 추가되는 .go 로직 파일은 root/internal/ 폴더 내에 기능별 하위 폴더를 생성하여 관리합니다.

• 표준 라이브러리 준수: Go 1.16+ 표준에 따라 사용이 중단된 ioutil 대신 os 패키지를 사용합니다.

  • ioutil.ReadFile → os.ReadFile

  • ioutil.WriteFile → os.WriteFile

사용자 경험 (UX) 처리

• UI 텍스트 선택 방지: 불필요한 툴바, 상태바 등에서 텍스트가 선택되지 않도록 CSS 처리를 적용합니다.

  .no-select {
    user-select: none;
    -webkit-user-select: none; /* Safari/macOS WebView 대응 */
  }
  

🍎 2. macOS 전용 최적화 (Native Experience)

네이티브 메뉴 구성

운영체제별로 메뉴 처리 방식을 분리하여 빌드 태그를 활용합니다.

• menu_darwin.go: 네이티브 메뉴(파일, 편집, 보기, 윈도우, 도움말) 및 About 다이얼로그 구현.

• 타이틀바: 최신 macOS 디자인 가이드를 준수하기 위해 TitleBarDefault()를 사용합니다.

• menu_other.go: Windows/Linux용 스텁(nil 반환) 처리.

프론트엔드 연동

메뉴 액션은 Wails의 EventsOn을 통해 프론트엔드와 통신합니다.

• 예시 이벤트: menu:open-file, menu:toggle-search 등

App Info (Info.plist) 설정

Info.plist에 앱의 고유 식별자와 저작권 정보를 포함합니다.

<key>CFBundleIdentifier</key>
<string>com.제작자.앱이름</string>
<key>NSHumanReadableCopyright</key>
<string>Copyright (C) 2026 제작자. All rights reserved.</string>

📋 3. macOS 클립보드(복사/붙여넣기) 발생시 문제 해결

문제 현상

macOS WebView의 보안 정책으로 인해 document.execCommand('paste')가 차단됩니다. 특히 Wails에서 Edit 메뉴 항목에 별도 콜백을 설정하면 네이티브 동작이 가로채져 작동하지 않는 경우가 발생합니다.

해결 방법

Edit 메뉴의 콜백을 **nil**로 설정하여 시스템이 네이티브 동작을 직접 수행하게 합니다.

• ❌ 잘못된 방법: 커스텀 콜백 설정

• ✅ 권장 방법: Wails 내장 EditMenu() 사용

// main.go 또는 메뉴 설정 파일
men := menu.NewMenu()

// Wails 내장 EditMenu 사용 시 클립보드가 정상 작동합니다.
men.Append(menu.EditMenu())

🖥️ 4. 시스템 다이얼로그 및 OS 호환성

다이얼로그 처리 전략

외부 프로그램 실행이나 시스템 확인 창 호출 시 호환성 문제를 방지합니다.

• Windows / Linux: 브라우저 형식의 다이얼로그 사용 가능.

• macOS: 반드시 네이티브 다이얼로그를 사용합니다. (브라우저 방식은 보안상 차단될 수 있음)

🎨 5. 운영체제별 앱 아이콘 경로

빌드 시 각 플랫폼에 맞는 아이콘 파일이 아래 경로에 위치해야 합니다.

플랫폼

아이콘 파일 경로

확장자

macOS

build/darwin/iconfile.icns

.icns

Linux

build/linux/icon.png

.png

Windows

build/windows/icon.ico

.ico

💡 Tip: 빌드 전 wails doctor를 통해 각 플랫폼별 빌드 환경이 정상인지 항상 확인하세요!

Go Wails Windows, macOS, Linux용 빌드 스크립트 작성 관련 지침

macOS용 퍼미션 문제를 해결하는 build 스크립트 지침

1. 지능적 서명 ID (Signing Identity) 관리

macOS 앱은 유효한 인증서로 서명되지 않으면 실행 시 차단되거나 권한 초기화 문제가 발생합니다. 이 스크립트는 이를 자동화했습니다.

• 자동 탐지: security find-identity 명령어를 통해 시스템에 설치된 'Developer ID Application' 또는 'Apple Development' 인증서를 우선적으로 찾습니다.

• 유연성: 환경 변수(MACOS_SIGN_IDENTITY)가 설정되어 있으면 이를 우선 사용하고, 인증서가 전혀 없을 경우 **Ad-hoc 서명(-)**으로 대체하여 최소한의 실행 가능성을 확보합니다.

2. 앱 번들 구조화 및 동적 라이브러리(dylib) 최적화

Wails와 같은 Go 기반 앱이 외부 라이브러리(ONNX Runtime 등)를 사용할 때 가장 빈번하게 발생하는 경로(Path) 문제를 해결했습니다.

• 배치(Placement): 외부 dylib 파일을 Contents/MacOS/ 내부, 즉 실행 파일과 동일한 위치에 배치합니다.

• RPATH 수정: install_name_tool을 사용하여 실행 파일이 라이브러리를 찾을 때 현재 실행 위치(@executable_path/)를 참조하도록 강제합니다.

  • install_name_tool -add_rpath "@executable_path/" ...

• ID 수정: 라이브러리 자체의 Identification Name을 @rpath/ 기준으로 변경하여 포터블(Portable)하게 만듭니다.

3. 코드 서명 무결성 확보 (Re-signing)

단순히 wails build만 하는 것이 아니라, 외부 파일이 추가된 후 전체 번들을 다시 서명하여 서명 깨짐 현상을 방지합니다.

• 속성 정리: xattr -cr을 사용하여 파일 다운로드 기록이나 검증을 방해하는 확장 속성(metadata)을 모두 제거합니다.

• 순차적 서명: 1. 먼저 의존성 파일(dylib)을 서명합니다.

  1. 그 다음 실행 파일을 서명합니다.

  2. 마지막으로 전체 앱 번들을 --deep 옵션으로 서명하여 계층적 무결성을 완성합니다.

• Hardened Runtime 적용: --options runtime을 부여하여 macOS의 강화된 런타임 보안을 준수합니다.

4. 권한 부여 (Entitlements) 및 샌드박스 대응

entitlements.plist를 서명 과정에 포함시켜 앱이 시스템 자원에 접근할 수 있는 명시적 권한을 부여합니다.

• --entitlements "$ENTITLEMENTS" 옵션을 통해 마이크, 카메라, 네트워크 사용 권한 등을 서명 데이터에 박아 넣습니다. 이는 나중에 앱 스토어 배포나 공증(Notarization) 시 필수적인 단계입니다.

💡 차후 빌드 스크립트 작성 시 참고 지침 (Summary)

단계

수행 작업

핵심 명령어/옵션

1. 환경 정리

이전 빌드 잔재 및 확장 속성 제거

rm -rf, xattr -cr

2. 라이브러리 링크

라이브러리 복사 및 경로(RPATH) 수정

install_name_tool

3. 서명 ID 확보

로컬 키체인에서 인증서 자동 추출

security find-identity

4. 개별 서명

dylib 및 바이너리 개별 서명

codesign --force --options runtime

5. 번들 최종 서명

권한(Entitlements) 적용 및 전체 서명

codesign --deep --entitlements ...

⚠️ 주의사항

• 공증(Notarization): 외부 배포용이라면 위 스크립트 이후 xcrun altool 또는 notarytool을 사용하여 Apple 서버에 공증을 받는 단계가 추가되어야 합니다.

• Ad-hoc의 한계: 인증서가 없어 -로 서명한 경우, 다른 사용자에게 배포 시 "확인되지 않은 개발자" 경고가 무조건 발생합니다. 외부 배포용은 반드시 유료 Apple Developer 계정의 인증서가 필요합니다.

Ubuntu(linux) 빌드 문제를 해결하는 build 스크립트 지침

1. 멀티 배포판 대응 의존성 자동 설치

리눅스는 배포판마다 패키지 관리자와 라이브러리 명칭이 다릅니다. 이 스크립트는 이를 감지하여 사용자 개입을 최소화합니다.

• 패키지 매니저 판별: apt-get, dnf, pacman, apk 등 주요 패키지 관리자의 존재 여부를 확인하여 시스템을 식별합니다.

• 권한 관리: 실행 사용자가 root가 아닐 경우 자동으로 sudo를 접두어로 사용하여 설치 명령을 수행하도록 설계되었습니다.

• 필수 도구 설치: GUI 앱 빌드에 필수적인 GTK3, WebKit2GTK, pkg-config, build-essential 등을 해당 배포판 명칭에 맞춰 설치합니다.

2. WebKit2GTK 버전 호환성 처리

Wails는 리눅스 웹뷰로 WebKit2GTK를 사용하는데, 시스템에 설치된 버전에 따라 빌드 태그를 명시해야 하는 경우가 있습니다.

• 자동 탐지: pkg-config를 사용하여 시스템에 설치된 버전이 4.0인지 4.1인지 확인합니다.

• 빌드 태그 동적 할당: 4.1 버전이 탐지될 경우, Go 컴파일러가 이를 올바르게 인식하도록 -tags webkit2_41 옵션을 wails build 명령에 추가합니다.

3. Go 및 Wails 환경 자동 구성

개발 환경이 완벽하지 않은 상태에서도 빌드가 가능하도록 환경 변수와 도구 설치를 스크립트 내에서 처리합니다.

• 경로 관리(PATH): Go 바이너리 경로(/usr/local/go/bin)와 Go로 설치한 도구 경로(GOPATH/bin)를 스크립트 세션의 PATH에 강제로 추가하여 명령 실행 실패를 방지합니다.

• Wails 자동 설치: Wails 커맨드가 없을 경우 go install을 통해 최신 버전을 자동으로 내려받고 설치 경로를 직접 참조하여 빌드를 이어갑니다.

💡 차후 리눅스 빌드 스크립트 작성 시 참고 지침 (Summary)

단계

수행 작업

핵심 명령어/전략

1. 의존성 체크

패키지 관리자별 라이브러리 설치

command -v [manager], pkg-config --exists

2. 환경 변수 설정

Go 및 Wails 실행 경로 확보

export PATH=$PATH:$(go env GOPATH)/bin

3. 컴파일 최적화

WebKit 버전에 따른 빌드 태그 적용

wails build -tags webkit2_41 (필요시)

이 지침을 활용하면 우분투뿐만 아니라 다양한 리눅스 배포판에서도 일관된 빌드 결과를 얻을 수 있는 강력한 스크립트를 구성할 수 있습니다.

Windows Wails CLI의 자동 빌드 기능에 의존하지 않고, 수동 빌드 프로세스를 통해 윈도우 환경 특유의 제약 사항을 해결

1. Wails CLI 한계 극복: 수동 빌드 전략

특정 윈도우 환경에서는 wails build 명령어가 제대로 작동하지 않을 수 있습니다. 이 스크립트는 이를 단계별 수동 명령으로 분해하여 안정성을 확보했습니다.

• [cite_start]바인딩 수동 생성: wails generate bindings를 통해 프론트엔드와 백엔드 간의 통신 코드를 먼저 생성합니다[cite: 4].

• [cite_start]표준 Go 빌드 활용: wails build 대신 go build를 직접 실행하여 빌드 프로세스에 대한 세밀한 제어권을 가집니다[cite: 4].

2. 윈도우 전용 리소스 및 메타데이터 주입

윈도우 실행 파일(.exe)은 아이콘, 버전 정보, 관리자 권한 요청 등의 메타데이터를 포함해야 합니다.

• [cite_start]리소스 컴파일: goversioninfo 도구를 사용하여 versioninfo.json을 resource_windows.syso 파일로 변환합니다[cite: 4].

• [cite_start]자동 링크: Go 컴파일러는 빌드 시 디렉토리에 있는 .syso 파일을 자동으로 감지하여 실행 파일의 속성(파일 버전, 저작권, 아이콘 등)으로 삽입합니다[cite: 4].

3. 컴파일러 플래그를 통한 바이너리 최적화

실행 파일의 크기를 줄이고 사용자 경험을 개선하기 위해 특정 빌드 플래그를 사용합니다.

• [cite_start]GUI 모드 강제: -H windowsgui 플래그를 사용하여 앱 실행 시 검은색 콘솔(CMD) 창이 함께 뜨지 않도록 설정합니다[cite: 4].

• [cite_start]용량 최적화: -s -w 플래그를 통해 디버깅 정보를 제거하여 바이너리 용량을 최소화합니다[cite: 4].

4. 윈도우 경로 및 DLL 의존성 관리

윈도우는 리눅스/macOS와 달리 라이브러리 검색 경로가 다르므로 DLL 파일 배치가 중요합니다.

• [cite_start]정리 작업: 빌드 과정에서 임시로 생성된 .syso 리소스 파일을 삭제하여 프로젝트 폴더를 깔끔하게 유지합니다[cite: 1, 6].

💡 차후 윈도우 빌드 스크립트 작성 시 참고 지침 (Summary)

단계

수행 작업

핵심 명령어/옵션

1. 환경 정리

기존 빌드 폴더 삭제 및 초기화

[cite_start]if exist ... rmdir /s /q [cite: 2]

2. 리소스 준비

아이콘 및 버전 정보 생성

[cite_start]goversioninfo -64 [cite: 4]

3. 수동 컴파일

콘솔 창 숨김 및 용량 최적화 빌드

[cite_start]go build -ldflags "-H windowsgui -s -w" [cite: 4]

4. DLL 배포

필수 런타임 라이브러리 동봉

[cite_start]copy /Y ... .dll [cite: 5]

5. 리소스 정리

임시 중간 파일 삭제

[cite_start]del *.syso [cite: 1, 6]

이 가이드는 윈도우 환경에서 발생할 수 있는 Wails CLI 오류, 불필요한 콘솔 창 노출, 실행 파일 메타데이터 누락 문제를 해결하는 표준 모델이 될 것입니다.