> ## 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 中使用 Windsurf（通过 **Remote - WSL**）时，编辑器可能会变得缓慢、无响应，或反复与 WSL 后端断开连接。最常见的原因是扩展在 WSL 文件系统上执行了高频文件监听和索引操作，从而导致 **Plan 9 (9P) 协议**（Windows 与 WSL Linux 环境之间的文件系统桥）出现饱和。

在大型代码仓库以及多个语言服务器并发运行时，更容易出现这种情况。

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

* 连接到 WSL 时，Windsurf 明显变慢或卡顿
* 编辑器经常与 WSL 后端断开连接并尝试重新连接
* 无论是在进行开发（例如使用 Cascade 时）**还是** 在编辑器空闲时，都会发生断连
* Windsurf 崩溃或无响应，需要同时重启 IDE 和 WSL（`wsl --shutdown`）
* 即使在拥有 32 GB 以上内存的系统上，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+ 内存的系统上，也可能压垮 9P 桥接层。

一个已知的示例是 **Vue (Volar) 扩展**，在 WSL 环境中，即使工作区并不包含 Vue 文件，也被观察到会触发过度的文件索引。这个问题已在 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)** —— 已确认会通过 9P 桥执行过量的文件索引，即使在非 Vue 项目中也是如此。仅仅卸载这个扩展，就已经为多位用户解决了断连问题。
* 其他特定框架的语言扩展（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">
  #### **检查 WSL 诊断日志中的 9P 错误**
</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 中安装了很多其实并不常用的扩展，或者是从其他编辑器迁移过来的扩展，请选择 **精简扩展（Minimize extensions）**。（这是影响最大的更改。）
* 如果 Windsurf 服务器的状态可能已经损坏或过期（例如更新失败或之前发生过崩溃），请选择 **重新干净安装服务器（Clean server reinstall）**。
* 如果 WSL 占用了过多宿主机资源，或者你之前从未配置过资源上限，请选择 **优化 `.wslconfig`（Optimize `.wslconfig`）**。（这是一项提升 WSL 稳定性的通用优化。）

为了获得最佳效果，建议三种方式都执行一遍。干净的服务器、精简的扩展以及调优后的资源限制三者结合，可以同时解决根本问题（扩展活动导致的 9P 饱和）以及相关诱因（资源耗尽）。

***

## **无法通过 VPN 或零信任软件连接到 WSL**

当 VPN 或零信任软件（Twingate、Tailscale、Zscaler、Cloudflare WARP、GlobalProtect 等）阻止了 WSL 内部的出站网络流量时，Windsurf 无法连接到 WSL，并显示错误 `Couldn't install vscode server on remote server, install script returned non-zero exit status`。

### **症状**

* 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. 启用镜像网络（mirrored networking）**

编辑 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 内访问网络。