---
title: ランチャー故障排查
description: 環境自律構築の失敗、ポート競合、プロキシとミラー設定、macOS/Linux 特有の依存関係、プロセス残存の対処法。
updated: 2026-10-20
---

# ランチャー故障排查

ランチャーで発生するエラーは大きく分けて**自律初期化フェーズのエラー**（環境構築の失敗）と、**ランタイムフェーズのエラー**（バックエンドは起動したが接続できない）の2種類に分類されます。エラー画面に表示される現在のフェーズを確認し、段階的に切り分けてください。

## <DocIcon name="rocket" /> 自律初期化フェーズ

| フェーズ | 症状 | 主な原因 | 対処方法 |
| --- | --- | --- | --- |
| `.venv` の作成 | 停止する / 権限エラー | フォルダが書き込み禁止、パスに特殊文字 | ユーザーホーム配下のパスへ配置場所を変更 |
| Python のダウンロード | タイムアウト / ハッシュ不一致 | 接続先ミラーの応答不良 | `-cn` 版を使用するか、ネットワーク環境を変更 |
| リポジトリの更新 | `git` コマンドの失敗 | プロキシ遮断、ブランチ不一致、ディスク満杯 | `deploy.yaml` を確認。`--skip-update` での起動を試行 |
| 依存関係の同期 | `uv sync` の失敗 | PyPI へのアクセス不能、ロックファイルの不整合 | ミラーソースを変更。コードと `uv.lock` の整合性を確認 |
| バックエンドの起動 | 起動直後に即時終了 | ポート競合、Python のクラッシュ | バックエンドログおよびポートの競合を確認 |
| ウィンドウ表示 | 画面が真っ白のまま | WebView ランタイムの欠落 | WebView2 または webkit2gtk をインストール |

### よく使われる復旧コマンド

```bash
# リポジトリ更新をスキップして起動
./alas-launcher --skip-update

# 依存関係を強制同期
uv sync --frozen

# 環境を完全に再構築（再度ダウンロードが行われます）
rm -rf .venv
```

::: danger .venv を削除しても設定は失われません
ユーザー設定は `config/` に、ログは `log/` に保存されています。ただし再構築にはインターネット接続が必要で、数分程度の時間がかかります。
:::

## <DocIcon name="plug" /> ポートの競合

| 現象 | 主な原因 | 対処方法 |
| --- | --- | --- |
| 「ポートが既に使用されています」と警告 | 別のランチャーまたはバックエンドがポート 22267 を占有中 | 残存している古いプロセスを終了 |
| バックエンドが起動しないがポートは空いている | ランチャーの指定ポートとコアの設定ポートの不一致 | `deploy.yaml` の `WebuiPort` を確認 |
| ポートを変更したが反映されない | WebView が依然として古いアドレスを参照している | ランチャー本体を再起動 |

ランチャーは起動時に当該ポートを占有している既存プロセスの検出とクリーンアップを試みます。ソースコード版（ポート 25548）と同時に実行する場合、ポートが異なるため競合しません。

## <DocIcon name="cloud" /> ネットワークとプロキシ

| 現象 | 主な原因 | 対処方法 |
| --- | --- | --- |
| リポジトリ更新のタイムアウト | GitHub への接続不良 | CN 版を使用、または `GitProxy` を設定 |
| Python のダウンロードが遅い | デフォルトの配布元への帯域制限 | ネットワークを変更、または手動でミラーを設定 |
| 依存関係インストール時に 403 エラー | 企業プロキシ等による通信ブロック | PyPI ミラーを設定するかホワイトリストに登録 |
| ブラウザでは開くがランチャー上で接続不能 | システムプロキシがローカルループバックを遮断 | ランチャーは `--no-proxy-server` で起動します。グローバルプロキシ設定を確認 |

## <DocIcon name="laptop" /> macOS 特有の問題

| 現象 | 対処方法 |
| --- | --- |
| 「悪質なソフトウェアが含まれているため開けません」 | ターミナルで `xattr -dr com.apple.quarantine /Applications/AzurPilot.app` を実行 |
| アプリを起動してもウィンドウが表示されない | コンソール（Console.app）でクラッシュログを確認。CPU アーキテクチャの適合を確認 |
| トレイアイコンが表示されない | メニューバーのアイコン過多による非表示。不要なトレイアイコンを整理 |

## <DocIcon name="wrench" /> Linux 特有の問題

| 現象 | 対処方法 |
| --- | --- |
| `libwebkit2gtk-4.1` の不足エラー | `apt install libwebkit2gtk-4.1-0` 等でライブラリを導入 |
| `GLIBC_2.xx not found` | ディストリビューションが古すぎます。ソースコード実行ルートへ移行してください |
| システムトレイが表示されない | GNOME 等で AppIndicator 拡張機能を有効化 |
| サンドボックスの権限エラー | Flatpak や Snap 等でラップせず、配布バイナリをネイティブ実行 |

## <DocIcon name="monitor" /> Windows 特有の問題

| 現象 | 対処方法 |
| --- | --- |
| UAC プロンプトで拒否される | 管理者権限での実行が必須です |
| SmartScreen による実行ブロック | 「詳細情報」をクリックし、「実行」を選択 |
| WebView2 の不足エラー | Evergreen ランタイムを Microsoft 公式から導入 |
| セキュリティソフトによる `git.exe` の隔離 | `.venv` フォルダを除外ホワイトリストに登録 |
| パス関連のエラー | 日本語やスペースを含まない英数字のみのパスへ移動 |

## <DocIcon name="circle-alert" /> プロセスの残存

| 現象 | 主な原因 | 対処方法 |
| --- | --- | --- |
| アプリ終了後も `python.exe` が残る | プロセス回収処理の異常終了 | ランチャーログのプロセススキャンを確認。PC を再起動 |
| エミュレーターが一緒に道連れ終了される | Windows Job Object の継承 | バックエンドとランチャーが breakaway に対応しているか確認 |
| 起動時にバックエンドが2重起動する | 単一インスタンス制御の失敗 | 関連プロセスをタスクマネージャーから全終了して再起動 |

仕様の詳細は[バックエンドプロセスのライフサイクル](/ja/launcher/developer/backend-lifecycle)を参照してください。

## <DocIcon name="scroll" /> ログの場所

```text
log/<日付>_launcher.txt
```

ここには自律初期化フェーズで実行された各コマンド、終了コード、処理時間が記録されます。原因究明時は末尾100行を抜粋して Issue に添付してください。

## <DocIcon name="refresh" /> ロールバック手順

1. 直前の正常なバージョンの圧縮アーカイブをダウンロードします。
2. 実行ファイルのみを上書き配置します（`.venv`、`config/` はそのまま保持）。
3. 新バージョンで `.venv` の内部構造が改変されていた場合は、`.venv` を削除して再構築させてください。

コアプログラムのコードのロールバックはランチャーとは独立して実行します：

```bash
git log --oneline -5
git checkout <コミットハッシュ>
uv sync --frozen
```