トラブルシューティング

まず renderer、Node Main、native host のどこで失敗しているかを分けます。murasaki dev で再現した後、実 artifact を build / launch してください。Vite build の成功だけでは、 packaging、code signing、runtime-discovered asset、別マシンの trust policy が動くことを証明できません。

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

terminal から実行し、stack の最終行ではなく最初の error を確認します。

pnpm exec murasaki dev

Murasaki は config.devPort（既定 5178）を検査し、使用中なら次の port に進みます。それでも待ち続ける / 終了する場合:

node --version で Node 22.12+ を確認
murasaki.config.ts が appId / productName を含む object を export しているか確認
src/main.ts を一時 rename、または main: false で Main startup を切り分け
選択された port を保持する古い dev process を終了
現 OS / architecture 用に dependency を再 install

main.ready() が resolve しない間、renderer は意図的に開きません。network 初期化に timeout を付け、各 startup resource の前後を log してください。

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

設定された Main entry file が lifecycle reload を開始します。resource ownership を entry に集め、shutdown() を idempotent にします。deep import した helper だけを変更し lifecycle restart が必要なら Main entry も保存してください。module-level socket / timer / child process は lifecycle から作成・close しないと残留することがあります。

dev では動くが bundle 後に動かない

installer を作る前に bundle をテストします。

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

主な原因:

Node dependency が bundler の検出できない file を動的 load する
native addon に target architecture 用 binary がない
MainContext.paths.data ではなく executable の隣に書き込む
process.cwd() を project root と仮定する
dev にだけ secret / .env があり installed app に provision されていない

resource path を明示し、clean VM / user account でテストしてください。現状の Node dependency packaging は、すべての native addon / runtime asset layout に対して Electron Forge や Tauri bundler と同等ではありません。

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

まず artifact を分類します。

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 signature を作る。ローカル bundle integrity は確認するが、信頼された developer identity にはならない
murasaki bundle --sign は Developer ID + hardened runtime
murasaki installer --sign --notarize は DMG の submit / staple も実行

自分の開発 / test artifact に限り quarantine attribute を外して再試行できます。

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

これを public installation flow として案内しないでください。警告なしの macOS 公開配布には Developer ID と notarization が必要で、ad-hoc signing では代替できません。

macOS の architecture が違う

launcher と同梱 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 で rebuild します。アプリ内のすべての native addon も target と一致する必要があります。cross-arch packaging は third-party native module を変換しません。

Windows installer が生成されない

bundle が成功すれば murasaki bundle --target win32-x64 は portable directory / .zip を生成します。installer format には外部 tool が必要です。

.exe: NSIS (makensis)。macOS / Windows から compile 可能
.msi: WiX v4。Windows 上で実行

どちらも PATH にない場合、installer は未生成と表示されます。portable zip を使うか必要 tool を install してください。--sign は Windows SDK SignTool も必要で、Windows 上で実行します。失敗する場合は PFX / store / Artifact Signing source が1つだけ選択され、 timestamp service へ接続でき、signtool verify /pa /v /tw <artifact> が成功するか確認します。

Shutdown が止まる / 途中で切られる

shutdown() の既定期限は 10 秒です。新規処理の受付を止め、context.signal で pending request を abort し、queue を待つ前に server を close します。計測済み要件がある場合だけ上限を増やします。

main: { shutdownTimeoutMs: 20_000 }

shutdown 内で無制限 retry をしないでください。強制終了は beforeQuit() のキャンセルを無視します。

Backend call が 403

/api/* と /__murasaki/* は app-local protected endpoint です。通常の browser tab、 curl、external client は HttpOnly runtime session を持たず 403 が正しい挙動です。 API route は app renderer から呼びます。public/local integration server が必要なら Node Main で別 listener を作り、独自に保護してください。

app renderer 自体が 403 になる場合、relative URL を使っているか、Host / Origin / cookie behavior を code が置換していないか確認します。

Update check が失敗する

次の順で確認します。

latest.json と latest.json.sig が隣接 URL にある
embedded publicKey と CI の private key が対になっている
manifest signature が upload 済み JSON の exact bytes を対象にしている
現在の <platform>-<arch> asset key がある
payload URL に到達でき、SHA-256 が一致する
download / install を dev ではなく bundle から実行している

診断のために signature verification を無効化しないでください。代わりに test keypair と manifest を作ります。自動更新も参照してください。