---
title: 更新・修復・アンインストール
description: コアプログラムとランチャーの2つの更新系統、環境破損時の修復手段、ログとキャッシュの場所、マシン移行と完全削除。
updated: 2026-10-20
---
# 更新・修復・アンインストール
ランチャー環境には2つの独立した更新系統が存在します：**ランチャー本体**と**コアプログラム**です。どちらが更新されたかを把握しておくことで、「UI の文言は変わったのに機能が変わっていない」といった疑問を解消できます。
## 2つの更新系統
| 項目 | コアプログラム | ランチャー本体 |
| --- | --- | --- |
| 更新方式 | 起動時の `git pull` ＋ `uv sync --frozen` | 自己自動更新（mTLS ＋ 複数ミラー） |
| 更新頻度 | `master` ブランチに追従（高頻度） | バージョン番号が付与された Release |
| 影響範囲 | ゲーム自動化機能、WebUI、API | 外枠ウィンドウ、起動フロー、プロセス管理 |
| ロールバック | `git checkout <コミットハッシュ>` | 旧バージョンのアーカイブへの差し替え |
### コアプログラムを更新した際の動作
1. 次回のランチャー起動時に `git pull` により最新のコードが取得されます。
2. `uv sync --frozen` が実行され、新しい `uv.lock` に基づいて依存ライブラリが同期されます。
3. `gui.py` の `ensure_frontend()` が `frontend/dist` を検査し、必要に応じてフロントエンドを再ビルドします（Node.js が必要です）。
4. WebUI をリロードすると最新機能が反映されます。実行中だったインスタンスは安全に再起動されます。
::: warning フロントエンドのビルドには Node.js が必要です
Windows 環境ではランチャーがシステム上の Node.js を自動検知し、未検出時は自動ダウンロードして導入します。Linux / macOS 環境では手動で Node.js を導入しておく必要があります。未導入の場合、フロントエンドの再ビルドに失敗する可能性があります。
:::
### ランチャー本体を更新した際の動作
- ランチャーの実行バイナリのみが差し替えられ、`.venv`、`config/`、`log/` はすべてそのまま保持されます。
- 新バージョンで Python のバージョンや基本ツールチェーンに変更があった場合は、`.venv` の再構築が自動実行されます（設定データには影響しません）。
- コアプログラムのコードが古いリビジョンへ巻き戻ることはありません。
### バージョン間の互換性
| 組み合わせ | 動作結果 |
| --- | --- |
| 新ランチャー ＋ 旧コア | 通常は問題なく動作。新ランチャーがコアの新 API を要求する場合は更新を促す警告を表示 |
| 旧ランチャー ＋ 新コア | 新しい内部プロトコル（パスワードレス認証やプロセス回収タグ等）が利用できない可能性あり |
| 両方とも旧バージョン | 既存機能は利用可能ですが、最新の修正パッチは適用されません |
互換性の確認はリポジトリの `CHANGELOG.md` およびリリースノートを参照してください。
## 環境の修復手順
### 依存関係の破損
症状：起動時に `ModuleNotFoundError`、`ImportError` が発生する、または `uv sync` が失敗する。
```bash
# プロジェクトルートで実行
uv sync --frozen
```
それでも解決しない場合：
```bash
# 仮想環境を削除し、ランチャーに再構築させる（依存関係が再ダウンロードされます）
rm -rf .venv # Windows の場合：rmdir /s /q .venv
```
::: danger .venv を削除しても設定は失われません
`.venv` は Python 実行環境のみを保持しており、ユーザー設定（`config/`）やログ（`log/`）は別の場所にあります。ただし再構築にはインターネット接続が必要で、数分程度の時間がかかります。
:::
### Git リポジトリの破損
症状：更新に失敗する、`fatal: not a git repository`、マージ競合の発生。
```bash
git status
git stash # ローカルの変更がある場合は一時退避
git pull --rebase
```
ローカルで編集した設定テンプレートやパッチを消失させないよう、安易に `git reset --hard` を実行しないでください。
### ポート競合の解消
ランチャーのデフォルトポートは `22267` です。ランチャー起動時に競合プロセスは自動終了されます。ソースコード版（デフォルト `25548`）と同時に稼働させる場合はポートが異なるため競合しませんが、ランチャーを2つ起動した場合は競合します。
### キャッシュのクリア
| ディレクトリ | 内容 | 削除の可否 |
| --- | --- | --- |
| `cache/` | ランタイムキャッシュ、画像データ等 | 削除可能（自動再生成） |
| `frontend/node_modules` | フロントエンドのビルド用依存関係 | 削除可能（ビルド時に再導入） |
| `frontend/dist` | フロントエンドのビルド成果物 | 削除可能（`gui.py` が再ビルド） |
| `log/` | ログファイル | 削除可能（トラブルシューティング時は保持を推奨） |
### ログファイルの場所
| ログ種別 | 格納場所 |
| --- | --- |
| ランチャー本体 | `log/<日付>_launcher.txt` |
| コアプログラム | `log/<日付>_<インスタンス>.txt` |
| エラー現場記録 | `log/error/<インスタンス>/<タイムスタンプ>/` |
ランチャーログには初期化フェーズのコマンドと結果が、コアプログラムログにはタスクの進行と画像認識の詳細が記録されます。Issue 起票時は両方の提出が求められます。
## 別マシンへのデータ移行
ファイル書き込み中の不整合を防ぐため、すべてのインスタンスを停止します。
`deploy.yaml` を含む `config/` ディレクトリ全体をコピーします。アカウントヴォールトはデバイス固有の暗号化キーに紐づいているため、移行先マシンで再登録が必要です。
新マシンにランチャーを展開して一度起動し、環境自律構築（`.venv` のセットアップ）が完了したら一度終了します。
コピーしておいた `config/` を新環境のルートディレクトリに上書き配置し、ランチャーを再起動します。
新マシンの環境に合わせて、エミュレーターの Serial、ADB パス、スクリーンショット方式を再設定します。
## 完全アンインストール
1. システムトレイのアイコンから「終了」を選び、`gui.py` などのプロセスが残存していないことを確認します。
2. 必要に応じて `config/` および `AzurPilot_Data_Backup/` を退避します。
3. ランチャーのディレクトリ全体を削除します。
4. OS のスタートアップに登録していた場合は、システム設定から該当の登録エントリを削除します。
## トラブルシューティングクイックリファレンス
| 現象 | 確認ポイント |
| --- | --- |
| 「Python のダウンロード」で停止する | 通信状況またはミラーの不調。`-cn` 版への変更や `deploy.yaml` の編集 |
| 「リポジトリ更新」で停止する | プロキシ設定、ブランチ名、GitHub への疎通。`--skip-update` での起動テスト |
| 「依存関係同期」で停止する | PyPI ミラーの接続性。`uv.lock` とコードのバージョンの不一致 |
| ウィンドウが真っ白のまま | WebView2 または libwebkit2gtk の不足 |
| ポート競合の警告が出る | 別のランチャープロセスが残存していないか確認 |
| ウィンドウを閉じてもタスクが続く | 正常な動作です（トレイに最小化されています） |
| トレイから終了しても python が残る | プロセス回収の失敗。ランチャーログのプロセススキャン記録を確認 |
| 更新後に WebUI が開かない | フロントエンドのビルド失敗。Node.js の導入状況と `frontend/dist` を確認 |
| macOS で「壊れているため開けません」 | `xattr -dr com.apple.quarantine /Applications/AzurPilot.app` を実行 |
プロセスのライフサイクルの詳細は[バックエンドプロセスのライフサイクル](/ja/launcher/developer/backend-lifecycle)を参照してください。