トラブルシューティング

まず、レンダラー、Node Main、ネイティブホストのどこで失敗しているかを切り分けます。murasaki dev で再現を確認した後、実際の配布物をビルドして起動してください。Vite のビルドが成功しても、パッケージング、コード署名、実行時に見つけるリソース、別のマシンの信頼設定まで正しく動作するとは限りません。

開発ウィンドウが開かない

ターミナルから実行し、スタックトレースの最終行ではなく、最初のエラーを確認します。

pnpm exec murasaki dev

Murasaki は config.devPort（デフォルト 5178）を確認し、使用中なら次のポートへ進みます。それでも待ち続ける、または終了する場合は、次を確認してください。

1. node --version で Node.js 22.12 以上であることを確認する
2. murasaki.config.ts が appId と productName を含むオブジェクトをエクスポートしているか確認する
3. src/main.ts の名前を一時的に変えるか、main: false を指定して Node Main の起動処理を切り分ける
4. 選択されたポートを使用している古い開発プロセスを終了する
5. 現在の OS とアーキテクチャ向けに依存パッケージを入れ直す

main.ready() が完了するまで、レンダラーは意図的に開きません。ネットワーク初期化にはタイムアウトを設け、起動時に確保する各リソースの前後でログを記録してください。

HMR は動くが Main の変更で再起動しない

設定した Node Main のエントリーファイルを変更すると、ライフサイクルが再読み込みされます。リソースの所有処理をエントリーへ集め、shutdown() は複数回呼ばれても安全な実装にしてください。深くインポートしたヘルパーだけを変更して再起動が必要な場合は、エントリーファイルも保存してください。モジュール直下で作成したソケット、タイマー、子プロセスは、ライフサイクル内で作成・終了しないと残ってしまう場合があります。

開発時は動作するがバンドル後に動作しない

インストーラーを作る前に、アプリバンドルをテストします。

pnpm exec murasaki bundle
open "dist/bundle/My App.app"                 # macOS
# または: dist\\bundle\\My App\\My App.exe     # Windows

主な原因:

• Node の依存パッケージが、バンドラーが検出できないファイルを動的に読み込んでいる
• ネイティブアドオンに対象アーキテクチャ向けのバイナリが含まれていない
• コードが MainContext.paths.data ではなく実行ファイルの隣に書き込んでいる
• コードが process.cwd() をプロジェクトルートだと仮定している
• 開発時にはあったシークレットや .env ファイルが、インストール後のアプリには配置されていない

リソースのパスを明示し、クリーンな仮想マシンまたはユーザーアカウントでテストしてください。現在の Node.js 依存パッケージの同梱処理は、あらゆるネイティブアドオンや実行時リソースの配置において Electron Forge や Tauri のバンドラーと同等というわけではありません。

macOS で「壊れている」「検証できない」と表示される

まず、成果物を分類します。

codesign -dvvv --entitlements :- "dist/bundle/My App.app"
codesign --verify --deep --strict --verbose=2 "dist/bundle/My App.app"
spctl -a -vv "dist/bundle/My App.app"
xattr -l "dist/bundle/My App.app"

• --sign を指定しない murasaki bundle は ad-hoc 署名 を作成します。ローカルでのバンドルの整合性は確認できますが、信頼できる開発者であることは証明されません
• murasaki bundle --sign は Developer ID と hardened runtime を使用します
• murasaki installer --sign --notarize は、さらに Gatekeeper 向けに DMG を提出してステープルまで行います

自分の開発用 / テスト用の成果物に限り、隔離属性を外して再試行できます。

xattr -dr com.apple.quarantine "dist/bundle/My App.app"

これを一般公開のインストール手順として案内しないでください。警告なしで macOS に一般公開するには Developer ID と公証が必要であり、ad-hoc 署名では代替できません。

macOS でアーキテクチャが一致しない

ランチャーと同梱された Node を確認します。

file "dist/bundle/My App.app/Contents/MacOS/My App"
file "dist/bundle/My App.app/Contents/Resources/node/bin/node"

Apple Silicon 向けには --arch arm64、Intel 向けには --arch x64 でリビルドします。アプリ内のすべてのネイティブアドオンも、対象のアーキテクチャに合わせる必要があります。クロスアーキテクチャでのパッケージングは、サードパーティ製のネイティブモジュールを自動的に変換するものではありません。

Windows のインストーラーが生成されない

バンドルが成功すれば、murasaki bundle --target win32-x64 は常にポータブルディレクトリと .zip を生成します。インストーラー形式の生成には外部ツールが必要です。

• .exe: NSIS（makensis）。macOS / Windows でコンパイル可能です
• .msi: WiX v4。Windows 上で実行します

どちらも PATH にない場合、murasaki installer はインストーラーが生成されなかったと報告します。ポータブル ZIP を使うか、必要なツールをインストールしてください。--sign には Windows SDK の SignTool も必要で、Windows 上で実行する必要があります。署名に失敗する場合は、PFX / store / Artifact Signing のいずれか1つの署名ソースだけが選択されていること、タイムスタンプサービスに接続できること、signtool verify /pa /v /tw <artifact> が成功することを確認してください。

シャットダウンが止まる、または途中で打ち切られる

shutdown() のデフォルトのタイムアウトは 10 秒です。新規リクエストの受付を停止し、context.signal で保留中のリクエストを中断してから、キューの完了を待つ前にサーバーをクローズします。計測に基づく明確な要件がある場合のみ、上限を増やしてください。

main: { shutdownTimeoutMs: 20_000 }

shutdown() の中で無制限にリトライしないでください。強制終了する場合、beforeQuit() によるキャンセルは無視されます。

Backend call が 403

/api/* と /__murasaki/* は、アプリ内部に閉じた保護対象のエンドポイントです。通常のブラウザタブや curl コマンド、外部クライアントはネイティブウィンドウが持つ HMAC 由来の識別情報を持たないため、403 が返るのは正しい挙動です。API Routes は、backendCapabilities でその正確なリソースへのアクセスを許可されたアプリのレンダラーから呼び出してください。公開用またはローカル用の連携サーバーが必要な場合は、Node Main 内に別のリスナーを作成し、独自に保護してください。

アプリのレンダラー自体が 403 になる場合は、backendCapabilities を確認し、相対 URL を使用し、ネイティブの document-start スクリプトが提供する fetch / XHR / EventSource のラッパーを置き換えないようにしてください。Host ヘッダーと Origin ヘッダーが、アプリケーションのオリジンのままであることも確認してください。

アップデートの確認が失敗する

次の順で確認します。

1. latest.json と latest.json.sig が隣接する URL に置かれているか
2. 埋め込まれた publicKey が CI で使われている秘密鍵と対になっているか
3. マニフェストの署名が、アップロード済み JSON の正確なバイト列を対象にしているか
4. 現在の <platform>-<arch> に対応するアセットキーが存在するか
5. ペイロード URL に到達でき、SHA-256 が一致するか
6. ダウンロードとインストールを、開発時ではなくバンドルから実行しているか

リリースを診断するために署名検証を無効化しないでください。代わりに、テスト用の鍵ペアとマニフェストを新しく作成してください。自動更新も参照してください。

解決しない場合

Murasaki のバージョン、OS のバージョン、アーキテクチャ、実行した正確なコマンド、最初に出たエラー、そして最小限の再現手順を添えてください。通常のバグは公開の GitHub Issue、脆弱性は非公開の Security Advisoryを使用してください。

次へ