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

# WSL 已知问题

> 排查 Devin Desktop 在 Windows Subsystem for Linux (WSL) 中运行时的已知问题，包括因 Plan 9（9P）文件系统饱和导致的性能下降，以及由 VPN 或零信任网络软件引起的连接失败。

本页介绍了在 Windows Subsystem for Linux (WSL) 中使用 Devin Desktop 时的已知问题及推荐的修复方法。

***

<div id="slow-performance-or-disconnections-9p-filesystem-saturation">
  ## **性能缓慢或频繁断连 (9P 文件系统饱和) **
</div>

在 WSL 中使用 Devin Desktop (通过 **Remote - WSL**) 时，编辑器可能会变慢、无响应，或反复与 WSL 后端断开连接。最常见的原因是扩展在 WSL 文件系统上进行高强度的文件监视和索引，导致 **Plan 9 (9P) 协议** (Windows 与 WSL Linux 环境之间的文件系统桥梁) 不堪重负。

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

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

* 连接到 WSL 时，Devin Desktop 会明显变慢或出现卡顿
* 编辑器会频繁与 WSL 后端断开连接，并尝试重新连接
* 断连会在活跃开发过程中 (例如使用 Cascade 时) **以及**编辑器空闲时发生
* Devin Desktop 会崩溃或失去响应，需要重启 IDE 和 WSL (`wsl --shutdown`)
* WSL 内存用量会随着时间推移不断增加，即使在配备 32 GB 以上 RAM 的系统上也是如此
* WSL 诊断日志中会显示大量 `P9 Reply_Rlerror` 事件 (文件未找到错误)
* 在 WSL 外使用 Devin Desktop 时，性能表现正常 (例如打开本地 Windows 文件夹)
* 常见的临时解决方法 (重启 WSL、重新安装 Devin Desktop、增加 `.wslconfig` 内存) 本身并不能解决该问题

***

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

Windows 与 WSL Linux 文件系统之间的通信使用 **Plan 9 (9P) 协议**，其吞吐量相比原生文件系统访问更有限。

当扩展安装在 WSL 环境中时，其中一些会对整个工作区进行高强度的文件监视和索引。在大型代码仓库中 (例如超过 250,000 个文件、5+ GB) ，这会通过 9P 桥接产生海量文件系统操作，从而可能：

* 使协议容量饱和
* 产生数千个“找不到文件”错误 (`Reply_Rlerror`)
* 导致 Devin Desktop 与 WSL 后端之间的连接中断
* 随着时间推移，进一步加重 WSL 内部的内存压力

如果同时还运行了多个语言服务器 (例如 Sorbet、Ruby LSP、TypeScript 等) ，情况会进一步恶化，因为它们会带来额外的文件监视开销。扩展和语言服务器共同产生的文件系统活动，即使在拥有 32 GB 以上内存的系统上，也可能让 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-update-wsl-to-the-latest-version-recommended-first-step">
  #### **1. 将 WSL 更新到最新版本 (建议先执行这一步) **
</div>

WSL 中许多断连和性能问题，只需更新 WSL 本身就能解决。较新的 WSL 版本改进了 9P 文件系统的稳定性和连接可靠性。

在你的 Windows 主机上打开 **PowerShell** (或命令提示符) ，然后运行：

```
wsl --update
```

然后重启 WSL：

```
wsl --shutdown
```

重新打开 Devin Desktop 并重新连接到 WSL。你可以使用以下命令检查你的 WSL 版本：

```
wsl --version
```

WSL **2.7.3.0 及更高版本**已包含相关修复，即使不做任何其他配置更改，也能解决用户持续出现的断连问题。

***

<div id="2-clean-reinstall-of-the-devin-desktop-server-in-wsl">
  #### **2. 在 WSL 中彻底重装 Devin Desktop 服务器**
</div>

删除 WSL 中的 Devin Desktop 服务器目录，让 Devin Desktop 在下次连接时重新安装它：

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

然后将 Devin Desktop 重新连接到 WSL。系统会自动重新安装服务端。

***

<div id="3-minimize-installed-extensions-highest-impact">
  #### **3. 尽量减少已安装的扩展 (影响最大) **
</div>

只安装你当前在所处理代码仓库中实际需要的扩展。

* 连接到 WSL 后，在 Devin Desktop 中打开“扩展”面板
* 检查安装在 **WSL** 环境中的扩展 (而不只是本地安装的扩展)
* 禁用或卸载你不需要的扩展——尤其是那些会大量监视文件或进行索引的扩展

**已知会在 WSL 中导致问题的扩展：**

* **Vue (Volar)** —— 已确认即使在非 Vue 项目中，它也会通过 9P 桥接造成过度的文件索引。仅卸载这一个扩展，就已经帮助多位用户解决了断连问题。
* 其他框架专用的语言扩展 (Angular、Svelte 等) 如果已安装但当前工作区并不需要，也可能出现类似情况。

**不要**想当然地认为在本地 (非 WSL) 环境中运行正常的扩展，在 WSL 中也会有相同表现。瓶颈在于 9P 文件系统桥接——在本地看似无害的扩展，一旦每次文件操作都必须跨越协议边界，就可能导致系统不稳定。

减少由扩展触发的文件系统活动，可以直接降低 9P 桥接的负载。

***

<div id="4-optimize-wsl-resource-limits">
  #### **4. 优化 WSL 资源限制**
</div>

在你的 **Windows** 主机上创建或编辑 `%USERPROFILE%\.wslconfig` 文件 (例如 `C:\Users\<YourUser>\.wslconfig`) ，并为你的系统设置合适的资源限制：

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

> **注意：** `autoMemoryReclaim` 设置已在 WSL **2.7.3.0** 及后续版本中移除。如果你使用的是 WSL 2.7.3.0+，请省略这一行。你可以使用 `wsl --version` 查看你的 WSL 版本。

请根据你系统的可用资源调整相应数值。

保存文件后，重启 WSL：

```
wsl --shutdown
```

然后重新打开 Devin Desktop，并重新连接到 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**——许多问题只需运行 `wsl --update` 就能解决。WSL 2.7.3.0 及以上版本包含显著的稳定性改进。 (最简单的修复方法。)
* 如果你在 WSL 中安装了很多当前并不需要的**扩展**，或者曾从其他编辑器迁移过扩展，请**尽量减少扩展数量**。 (效果最明显的改动。)
* 如果 Devin Desktop 的服务器状态可能已损坏或陈旧 (例如更新失败后，或之前发生崩溃后) ，请执行**干净重装服务器**。
* 如果 WSL 占用了过多主机资源，或者你之前没有配置过资源限制，请**优化 `.wslconfig`**。 (可普遍提升 WSL 稳定性。)

为获得最佳效果，请先更新 WSL，再根据需要应用其余修复方法。将 WSL 更新到最新、使用干净的服务器环境、尽量减少扩展，并合理调整资源限制，这种组合既能解决根本原因 (扩展活动导致的 9P 饱和) ，也能缓解促成因素 (资源耗尽) 。

***

<div id="cannot-connect-to-wsl-with-vpn-or-zero-trust-software">
  ## **使用 VPN 或零信任软件时无法连接到 WSL**
</div>

当 VPN 或零信任软件 (Twingate、Tailscale、Zscaler、Cloudflare WARP、GlobalProtect 等) 阻止 WSL 内部的出站网络流量时，Devin Desktop 在连接到 WSL 时会失败，并报错 `Couldn't install vscode server on remote server, install script returned non-zero exit status`。

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

* Devin Desktop 连接到 WSL 时报告 `Error resolving authority` / `install script returned non-zero exit status`
* WSL 本身工作正常 (`wsl -d Ubuntu -- echo hello` 可成功执行) ，但在 WSL 内运行 `curl` 会超时
* 安装或更新 VPN 或零信任软件后，开始出现该问题

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

默认情况下，WSL 2 会通过基于 NAT 的虚拟网络路由流量。VPN 和零信任软件通常不会转发来自这个虚拟网络的流量，因此服务器下载会在无任何提示的情况下失败。

<div id="solution">
  ### **解决方法**
</div>

<div id="1-enable-mirrored-networking">
  #### **1. 启用镜像网络模式**
</div>

编辑 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"
```

重新打开 Devin Desktop，并重新连接到 WSL。服务端会自动安装。

> **注意：** 需要 WSL 2.0.0 或更高版本。运行 `wsl --version` 检查版本，如有需要，运行 `wsl --update` 进行升级。

<div id="2-alternative-temporarily-disconnect-vpn">
  #### **2. 备选方案：临时断开 VPN**
</div>

如果你无法更改 `.wslconfig`，请先断开 VPN/ZTNA，让 Devin Desktop 安装服务端，然后再重新连接。今后更新 Devin Desktop 时，仍会再次需要 WSL 具备网络访问能力。