> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WSL の既知の問題

> Windows Subsystem for Linux (WSL) 上で Windsurf を実行する際の既知の問題をトラブルシューティングします。Plan 9 (9P) ファイルシステム飽和によるパフォーマンス低下や、VPN またはゼロトラストネットワークソフトウェアによる接続失敗について説明します。

このページでは、Windows Subsystem for Linux (WSL) で Windsurf を使用する際の既知の問題と推奨される修正方法について説明します。

***

## **パフォーマンス低下または切断（9P ファイルシステム飽和）**

WSL 上で（**Remote - WSL** 経由で）Windsurf を使用していると、エディタが遅くなったり、応答しなくなったり、WSL バックエンドとの接続が繰り返し切断されたりすることがあります。これは主に、WSL ファイルシステム上で過剰なファイル監視やインデックス作成を行う拡張機能が原因で発生し、その結果として、Windows と WSL Linux 環境間のファイルシステムブリッジである **Plan 9 (9P) プロトコル** が飽和してしまうことによります。

この問題は、特に大規模なリポジトリを扱っている場合や、複数の言語サーバーが同時に動作している場合に発生しやすくなります。

<div id="symptoms">
  ### **症状**
</div>

* WSL に接続しているとき、Windsurf の動作が明らかに遅い、またはカクつく
* エディタが頻繁に WSL バックエンドから切断され、再接続を試みる
* 切断は、（Cascade を使用しているときなどの）アクティブな開発中 **および** エディタがアイドル状態のときの両方で発生する
* Windsurf がクラッシュしたり応答しなくなり、IDE と WSL（`wsl --shutdown`）の両方を再起動する必要がある
* 32 GB 以上の RAM を搭載したシステムでも、時間の経過とともに WSL のメモリ使用量が増加していく
* WSL の診断ログに、大量の `P9 Reply_Rlerror` イベント（ファイルが見つからないエラー）が記録される
* WSL の外で Windsurf を使用している場合（例: ローカルの Windows フォルダを開く）、パフォーマンスは正常である
* 一般的な回避策（WSL の再起動、Windsurf の再インストール、`.wslconfig` のメモリ増量）だけでは問題が解決しない

***

<div id="root-cause">
  ### **根本原因**
</div>

Windows と WSL の Linux ファイルシステム間の通信には、ネイティブなファイルシステムアクセスと比べてスループットが限られている **Plan 9 (9P) プロトコル** が使われています。

拡張機能が WSL 環境内にインストールされている場合、その一部はワークスペース全体に対して積極的なファイル監視やインデックス作成を行います。大規模なリポジトリ（例: 25 万以上のファイル、5 GB 以上）では、これによって 9P ブリッジ越しに膨大な量のファイルシステム操作が発生し、結果として次のような問題が起こりえます:

* プロトコルの処理能力が飽和する
* 数千件規模の「ファイルが見つからない」エラー (`Reply_Rlerror`) が発生する
* Windsurf と WSL バックエンド間の接続が切断される
* 時間の経過とともに WSL 内でメモリプレッシャーが増大する一因となる

これに加えて、複数の言語サーバー（例: Sorbet、Ruby LSP、TypeScript など）が同時に動作していると、さらにファイル監視のオーバーヘッドが発生します。拡張機能と言語サーバーによるファイルシステムアクティビティが合わさることで、32 GB 以上の RAM を搭載したシステムであっても 9P ブリッジが飽和してしまう可能性があります。

既知の例として **Vue (Volar) 拡張機能** があり、ワークスペースに Vue ファイルが含まれていない場合でも、WSL 環境で過剰なファイルインデックス作成を引き起こすことが確認されています。この問題は VS Code エコシステムでも文書化されています:
[microsoft/vscode-remote-release#11091](https://github.com/microsoft/vscode-remote-release/issues/11091)

特に、現在のプロジェクトには不要な VS Code や他のエディタから引き継いだ多数の拡張機能がインストールされている場合に、こうした問題が発生しやすくなります。

***

<div id="solutions">
  ### **解決方法**
</div>

<div id="1-clean-reinstall-of-the-windsurf-server-in-wsl">
  #### **1. WSL 内での Windsurf サーバーのクリーン再インストール**
</div>

WSL 内の Windsurf サーバーディレクトリを削除し、次回接続時に Windsurf が自動的に再インストールするようにします。

```shell theme={null}
rm -rf ~/.windsurf-server
```

その後、Windsurf を WSL に再接続してください。サーバーは自動的に再インストールされます。

***

<div id="2-minimize-installed-extensions-highest-impact">
  #### **2. インストールする拡張機能を最小限にする（効果大）**
</div>

作業中のリポジトリで本当に必要な拡張機能だけをインストールしてください。

* WSL に接続した状態で Windsurf の Extensions パネルを開く
* **WSL** 環境にインストールされている拡張機能（ローカル側ではなく）を確認する
* 不要な拡張機能を無効化またはアンインストールする — 特に重いファイル監視やインデックス作成を行うもの

**WSL で問題が確認されている拡張機能:**

* **Vue (Volar)** — 非 Vue プロジェクトでも、9P ブリッジ越しに過剰なファイルインデックス作成を引き起こすことが確認されています。この拡張機能をアンインストールするだけで、複数ユーザーの切断問題が解消されています。
* その他のフレームワーク固有の言語拡張機能（Angular、Svelte など）も、現在のワークスペースで不要なのにインストールされている場合、同様の挙動をする可能性があります。

ローカル（非 WSL）環境で問題なく動作する拡張機能が、WSL でも同じように振る舞うと**決めつけないでください**。ボトルネックになっているのは 9P ファイルシステムブリッジであり、ローカルでは無害な拡張機能でも、すべてのファイル操作がプロトコル境界を越える必要がある環境では不安定要因になり得ます。

拡張機能によるファイルシステムへのアクセスを減らすことは、そのまま 9P ブリッジへの負荷削減につながります。

***

<div id="3-optimize-wsl-resource-limits">
  #### **3. WSL のリソース制限を最適化する**
</div>

**Windows** ホスト上で `%USERPROFILE%\.wslconfig` ファイル（例: `C:\Users\<YourUser>\.wslconfig`）を作成または編集し、システムに適したリソース制限を設定します。

```
[wsl2]
memory=16GB
swap=4GB
processors=4
autoMemoryReclaim=gradual
```

お使いのシステムで利用可能なリソースに応じて値を調整してください。

ファイルを保存したら、WSL を再起動してください。

```
wsl --shutdown
```

その後、Windsurf を再度開き、WSL に再接続してください。

***

<div id="diagnosis">
  ### **診断**
</div>

<div id="check-wsl-diagnostic-logs-for-9p-errors">
  #### **9P エラーの WSL 診断ログを確認する**
</div>

原因が 9P の飽和であることを確認するには、WSL の診断ログを収集してください。

```
wsl --debug-shell
```

あるいは、完全な診断バンドルを取得します：

```
Invoke-WebRequest -UseBasicParsing "https://aka.ms/wsldiag" -OutFile wsldiag.ps1
.\wsldiag.ps1
```

9P/ファイルシステムのログ内で `Reply_Rlerror` イベントが高頻度で発生していないか確認してください。数千件（またはそれ以上）のイベントが記録されている場合、WSL 内の拡張機能やプロセスが過剰なファイルシステム要求を発行しており、9P ブリッジがそれに追いつけていない可能性があります。

***

<div id="when-to-use-which-fix">
  ### **どの対処法をいつ使うか**
</div>

* WSL に多数の拡張機能をインストールしていて実際にはあまり使っていない場合、または別のエディタから拡張機能を移行してきた場合は、**拡張機能を最小限に抑えます**（最も効果の高い変更です）。
* **サーバーのクリーン再インストール**は、Windsurf サーバーの状態が破損している、または古くなっている可能性がある場合（例：アップデートの失敗や過去のクラッシュ後など）に実行します。
* **`.wslconfig` の最適化**は、WSL がホストのリソースを過剰に消費している場合、またはこれまでリソース制限を設定していない場合に行います（WSL 全体の安定性向上につながります）。

最良の結果を得るには、3 つすべてを適用してください。クリーンなサーバー、最小限の拡張機能、調整されたリソース制限の組み合わせにより、根本原因（拡張機能の動作による 9P の飽和）と、それに寄与する要因（リソース枯渇）の両方に対処できます。

***

## **VPN またはゼロトラストソフトウェア使用時に WSL に接続できない**

VPN またはゼロトラストソフトウェア（Twingate、Tailscale、Zscaler、Cloudflare WARP、GlobalProtect など）が WSL 内部からのアウトバウンドネットワークトラフィックをブロックしている場合、Windsurf は `Couldn't install vscode server on remote server, install script returned non-zero exit status` エラーで WSL への接続に失敗します。

### **症状**

* Windsurf が WSL への接続時に `Error resolving authority` / `install script returned non-zero exit status` を報告する
* WSL 自体は動作する（`wsl -d Ubuntu -- echo hello` は成功する）が、WSL 内部で `curl` がタイムアウトする
* VPN またはゼロトラストソフトウェアのインストールまたはアップデート後に問題が発生した

### **根本原因**

WSL 2 はデフォルトで NAT ベースの仮想ネットワークを通じてトラフィックをルーティングします。VPN やゼロトラストソフトウェアは、この仮想ネットワークからのトラフィックを転送しないことが多いため、Windsurf サーバーのダウンロードがサイレントに失敗します。

### **解決方法**

#### **1. ミラーリングネットワークを有効にする**

WSL 設定ファイルを編集してミラーリングネットワークを有効にします（通常 `C:\Users\<YourUser>\.wslconfig`）。
以下を追加してください：

```ini theme={null}
[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
```

その後、WSL を再起動し、古いインストール状態をクリーンアップします：

```
wsl --shutdown
wsl -d Ubuntu -- bash -c "rm -f ~/.windsurf-server/.installation_lock"
```

Windsurf を再度開き、WSL に再接続してください。サーバーは自動的にインストールされます。

> **注意:** WSL 2.0.0+ が必要です。`wsl --version` でバージョンを確認し、必要に応じて `wsl --update` でアップデートしてください。

#### **2. 代替策：VPN を一時的に切断する**

`.wslconfig` を変更できない場合は、VPN/ZTNA を切断し、Windsurf にサーバーをインストールさせてから再接続してください。将来の Windsurf アップデートでは、再び WSL からのネットワークアクセスが必要になります。