デバッグ

murasaki dev は2つのプロセスを同時に実行します。一方のプロセスでは、Node Main のライフサイクルをプラグインとして読み込んだ Vite の開発サーバーが動作し、もう一方のプロセスでは、メインスレッド上でネイティブの WebView ホストが動作します。それぞれデバッグの方法が異なります。このページでは WebView とレンダラー、その中の React ツリー、そして長寿命の Node Main プロセスを扱います。パッケージング、署名、起動時の問題については、トラブルシューティングを参照してください。

WebView の DevTools

murasaki dev は、ネイティブバイナリ自体がデバッグビルドかリリースビルドかに関わらず、常に DevTools を有効にしてウィンドウを開きます。パッケージ済みのアプリはその逆で、DevTools は常にコンパイル時に除去され、配布ビルドで DevTools を再度有効にするための設定フラグはありません。

• macOS は WKWebView を使用しており、それ自体に DevTools の UI はありません。Safari の Develop メニューを有効にし（Safari → 設定 → 詳細 → Show features for web developers）、Develop → <あなたの Mac> → localhost から、実行中のウィンドウへ Safari の Web Inspector をアタッチします。
• Windows は WebView2 を使用しており、Chromium 自身の DevTools を直接埋め込んでいます — ウィンドウを右クリックして Inspect を選ぶか、F12 を押します。

右クリックで OS ネイティブのメニュー（Inspect を含む）が開くのは、ウィンドウが useContextMenu で独自のメニューを宣言していない場合だけです。ウィンドウ全体のコンテキストメニューを宣言すると、それ以降はそのウィンドウを右クリックすると自分のメニューが開くようになります。F12 は Windows ではどちらの場合でも動作します。Murasaki は自分で宣言したショートカットに一致するキーだけをインターセプトするため、該当しないキーはそのまま WebView2 に渡されます。

ブラウザで React DevTools を使う

murasaki dev はアプリをカスタムプロトコルではなく実際の HTTP（http://127.0.0.1:<port>/）で配信するため、同じ URL をネイティブウィンドウと並べて Chrome で開くことができます。標準の React DevTools ブラウザ拡張機能は、ほかの普通のページと同様にアタッチでき、特別な統合は不要です。

ただし、普通のブラウザタブはアプリ本体ではありません。/api/* と /__murasaki/* はネイティブ WebView のセッションによって保護されているため、その Chrome タブから行う Server Actions や API Routes の呼び出しは、正しく 403 になります。React ツリーの確認にはタブを使い、アプリ自体の動作確認にはネイティブウィンドウを使ってください。Backend call が 403 を参照してください。

開発時のエラーオーバーレイ

キャッチされなかったエラーは、空白のウィンドウやコンソールだけのスタックトレースの代わりに、murasaki ブランドのフルスクリーンオーバーレイとして表示されます。次の3つのキャプチャ経路から供給されます。

• レンダーエラー（エラーバウンダリの componentDidCatch 経由）
• キャッチされなかった例外（window.onerror 経由）
• 処理されなかった Promise の拒否（unhandledrejection 経由）

オーバーレイは常に最新のエラーを、そのスタックと（レンダーエラーの場合は）React コンポーネントスタックとともに表示し、バッジでキュー内に残っている以前のエラー数を示します。連続する同一のエラーは重複排除されるため、React Strict Mode の二重呼び出しや再レンダリングでオーバーレイが同じエラーだらけになることはありません。Esc または Dismiss ボタンで閉じ、Reload でページを再読み込みします。本番ビルドでは何もしません — オーバーレイ全体がコンパイル時に除去されます。

Node Main をデバッグする

Node Main は、murasaki dev が起動する開発サーバーと同じプロセス内で Vite プラグインとして動作します。そのため、ready()、shutdown()、または任意の 'use main' 関数内で使う普通の console.log は、murasaki dev を実行したターミナルへそのまま出力されます。

context.log はこれとは意図的に異なる仕組みです。そのターミナルには一切出力されません。log.info / warn / error / debug の呼び出しはすべて、JSON Lines 形式で paths.logs/murasaki-main.jsonl にのみ書き込まれ、5 MiB でローテーションし、過去5世代分（.1 … .5）を保持します。構造化ログの出力をリアルタイムで確認したい場合は、そのファイル（または OS のログビューアー）を tail してください。

各行は { timestamp, level, message, fields? } の形式です。キー名が認証情報らしく見えるフィールド値（authorization、cookie、password、secret、token、apiKey、privateKey など)は、書き込み前に [redacted] へ置き換えられます。完全なマスキングとサイズ制限のルール、および上限付きのログ末尾とアプリケーション / ランタイムのメタデータを1つの共有可能な JSON ファイルにまとめて paths.logs/diagnostics/ 以下へ出力する createDiagnosticReport() については、Node Main → ログと診断レポートを参照してください。

Sidecar の出力

sidecar の stdout / stderr は、sidecar.onEvent()を通じてのみ受け取れます。各チャンクは 64 KiB で上限に達し、それを超えると末尾に …[truncated] が付きます。また、murasaki-main.jsonl へ自動的に書き込まれることもありません。そこにも記録したい場合は、ハンドラー内で自分でログしてください。

indexer.onEvent((event) => {
  if (event.type === 'stderr') log.warn('indexer stderr', { output: event.data })
})

パッケージ済みの Windows アプリをデバッグする

パッケージ済みのアプリには、デフォルトでは見えるコンソールがありません。murasaki.config.ts で window.console: true を設定すると、Windows でバックエンドの Node コンソールウィンドウを表示できます — 一時的な CLI やデバッグ出力に便利です。それ以外で起動後に必要な情報は、両プラットフォームとも paths.logs と createDiagnosticReport() を頼ってください。このリリースでは、Node Main 向けに Node の --inspect デバッガーポートは配線されていません。console.log（開発時）と context.log が、現時点でサポートされている手段です。

よくある問題

• ポートがすでに使用中。 murasaki dev は config.devPort（デフォルトは 5178）を確認し、自動的に次の空きポートへ移ります。開発ウィンドウが開かないとdevPortを参照してください。開発サーバー自体が起動に失敗する場合は、MURASAKI_DEBUG=1 を付けて再実行すると、ブランド付きの1行メッセージの代わりに完全なスタックトレースが得られます。
• Windows で WebView2 が見つからない、または古い。 Murasaki の Windows 用 WebView は、同梱の Chromium ではなく Microsoft Edge WebView2 です。現行の WebView2 Runtime がないマシンでは、ウィンドウをまったくレンダリングできません。Windows 11 と更新済みの Windows 10 の大半にはすでに入っていますが、入っていない場合は、ほかの問題を調べる前に Microsoft から Evergreen Runtime をインストールしてください。
• macOS で「壊れている」と表示される、または署名されていないビルドを Gatekeeper がブロックする。 ad-hoc 署名された開発用の成果物では想定内の挙動です。トラブルシューティングの macOS 関連の項を参照してください。

次へ