Wails로 데스크톱 앱 만들기 #8 디버깅 — 개발자 도구·로그·흔한 에러

프레임워크 Wails 고 데스크톱
5 분 소요

시리즈의 마지막 글입니다. 앞의 일곱 편이 “무엇을 어떻게 만드는가"였다면, 이번 글은 “안 될 때 어떻게 찾는가"입니다. 입문자가 Wails에서 가장 자주 막히는 지점, 곧 빈 화면·바인딩 오류·환경 문제를 개발자 도구와 로그로 잡는 법을 모았습니다. 디버깅을 알면 막혔을 때 검색만 반복하지 않고 원인으로 바로 갈 수 있습니다.

이 시리즈는 본편 6편 + 심화 2편, 총 8편입니다.

개발자 도구: 프론트엔드를 들여다보기 #

Wails 앱의 화면은 OS의 WebView로 그려지므로, 브라우저와 똑같은 개발자 도구를 쓸 수 있습니다. wails dev로 띄운 개발 모드에서는 개발자 도구가 기본으로 켜져 있습니다. 창에서 우클릭해 검사(Inspect)를 열거나 단축키로 엽니다. 여기서 DOM, 네트워크, 그리고 프론트엔드 콘솔을 브라우저처럼 봅니다.

주의할 점은 wails build로 만든 배포용 앱에서는 개발자 도구가 기본으로 꺼진다는 것입니다. 배포된 앱의 문제를 재현해 봐야 할 때는 뒤에 나오는 -debug 빌드를 씁니다.

로그: 프론트엔드와 Go 양쪽 #

Wails 앱은 두 세계가 붙어 있으므로 로그도 두 곳에서 나옵니다.

  • 프론트엔드 로그: console.log가 개발자 도구 콘솔에 찍힙니다. 브라우저와 같습니다.
  • Go 로그: #5에서 다룬 runtime.LogInfo·LogError 등이 있습니다. wails dev로 돌리면 이 Go 로그가 터미널에 찍힙니다. 프론트엔드 콘솔이 아니라 앱을 실행한 터미널을 봐야 합니다.

문제가 프론트엔드에 있는지 Go에 있는지 가를 때, 두 로그를 나눠 보는 것이 첫걸음입니다. 바인딩 호출이 실패하면 프론트엔드 콘솔에 거부된 Promise가, Go 안에서 무언가 잘못되면 터미널에 로그가 나옵니다.

흔한 에러 ①: 창은 뜨는데 화면이 비어 있다 #

가장 자주 겪는 증상입니다. 창은 열리는데 안이 하얗게 비어 있습니다. 원인은 대개 프론트엔드 빌드 결과가 Wails가 기대한 위치에 없다는 것입니다.

  • 프론트엔드를 빌드하지 않았거나(frontend:build 실패), Vite의 출력 경로가 Wails 기대 위치(frontend/dist)와 어긋난 경우입니다. #7에서 프레임워크를 붙일 때 자주 나옵니다.
  • 개발자 도구 콘솔을 열어 보면 대개 파일을 못 찾는 404나 자바스크립트 에러가 찍혀 있어, 어느 쪽인지 바로 드러납니다.

빈 화면을 만나면 추측하지 말고 개발자 도구 콘솔부터 엽니다. 화면이 비어 있어도 콘솔은 원인을 말해 줍니다.

흔한 에러 ②: 바인딩을 못 찾는다 #

프론트엔드에서 Go 메서드를 부르는데 “함수가 없다"거나 import가 깨지는 경우입니다. 체크리스트는 이렇습니다.

  • 메서드가 노출 규칙을 지켰나: 바인딩되려면 App 구조체의 메서드가 대문자로 시작(export) 해야 하고, 앱 생성 시 바인딩 목록에 등록되어 있어야 합니다(#3 참조).
  • 바인딩이 재생성됐나: wailsjs 폴더의 바인딩은 wails dev나 wails build가 Go 코드를 보고 다시 만듭니다. 메서드를 새로 추가했는데 안 보이면, 개발 서버를 껐다 켜 바인딩을 재생성합니다.

즉 “대문자·등록·재생성” 세 가지를 순서대로 확인하면 대부분 잡힙니다.

흔한 에러 ③: context가 nil이다 #

Go 런타임 함수(runtime.EventsEmit, runtime.WindowShow 등)를 부를 때 앱이 죽거나 아무 일도 안 일어나는 경우입니다. 이 함수들은 context.Context를 받는데, 그 값은 OnStartup이 불린 뒤에야 유효합니다. 앱이 완전히 시작하기 전에 런타임 함수를 부르면 context가 비어 있어 실패합니다.

app.go — context는 OnStartup에서 저장 
func (a *App) startup(ctx context.Context) {
	a.ctx = ctx // 이 시점부터 runtime 함수를 안전하게 쓸 수 있다
}

런타임 함수는 startup 이후에, 저장해 둔 a.ctx로 부릅니다. 초기화 순서 문제라, 로그를 찍어 어느 시점에 불렸는지 보면 금방 드러납니다.

배포된 앱 진단: -debug 빌드 #

wails dev에서는 멀쩡한데 빌드한 앱에서만 문제가 나는 경우가 있습니다. 이때는 개발자 도구와 로그를 켠 채로 빌드합니다.

개발자 도구·로그를 켜서 빌드 
wails build -debug

-debug로 만든 앱은 배포용과 같은 방식으로 돌면서도 개발자 도구를 열 수 있고 로그가 남습니다. 개발 모드에서 안 잡히는 “빌드된 상태에서만 나는 버그"를 재현하는 데 씁니다. 원인을 찾은 뒤에는 -debug 없이 다시 빌드해 배포합니다.

환경 문제: wails doctor #

빌드 자체가 안 되거나 이상하게 동작하면, 코드보다 환경을 먼저 의심합니다. #1에서 소개한 wails doctor가 Go 버전, WebView 런타임, 필수 의존성 같은 환경을 점검해 무엇이 빠졌는지 알려 줍니다. “내 코드는 그대로인데 갑자기 안 된다"의 상당수가 OS 업데이트나 의존성 변화이므로, 막히면 wails doctor를 한 번 돌려 봅니다.

정리 #

  • 개발자 도구는 wails dev에서 기본으로 켜집니다. 창 우클릭으로 열어 DOM·네트워크·콘솔을 브라우저처럼 봅니다. 빌드된 앱에서는 기본으로 꺼집니다.
  • 로그는 두 곳입니다. 프론트엔드는 console.log가 개발자 도구에, Go의 runtime.LogX는 wails dev를 돌린 터미널에 찍힙니다.
  • 빈 화면은 대개 프론트엔드 빌드 결과가 기대 위치에 없어서입니다. 추측 말고 콘솔부터 엽니다.
  • 바인딩을 못 찾으면 대문자 export·바인딩 등록·재생성 세 가지를 확인합니다. context가 nil이면 OnStartup 이후에 부르는지 봅니다.
  • 빌드된 앱만의 문제는 wails build -debug로 재현하고, 빌드 자체가 안 되면 wails doctor로 환경을 먼저 점검합니다.
  • 이상으로 Wails로 데스크톱 앱 만들기 시리즈를 마칩니다. 더 깊이 들어가려면 Wails 실전 강좌에서 하나의 앱을 배포와 완성도까지 만듭니다.
X