Wails でデスクトップアプリを作る #8 デバッグ — 開発者ツール・ログ・よくあるエラー

フレームワーク Wails Go デスクトップ
読了 5分

シリーズ最後の記事です。前の 7 編が「何をどう作るか」だったとすれば、この記事は「動かないときにどう見つけるか」です。入門者が 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 か JavaScript のエラーが出ていて、どちらかがすぐ分かります。

空の画面に出会ったら推測せず、開発者ツールのコンソールから開きます。画面が空でも、コンソールは原因を教えてくれます。

よくあるエラー ②: バインディングが見つからない #

フロントエンドから 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