跳转到主要内容
本页列出了在 Windows Subsystem for Linux (WSL) 中使用 Windsurf 时的已知问题及其推荐的解决方案。

​
性能缓慢或断连（9P 文件系统饱和）

当在 WSL 中使用 Windsurf（通过 Remote - WSL）时，编辑器可能会变得缓慢、无响应，或反复与 WSL 后端断开连接。最常见的原因是扩展在 WSL 文件系统上执行了高频文件监听和索引操作，从而导致 Plan 9 (9P) 协议（Windows 与 WSL Linux 环境之间的文件系统桥）出现饱和。 在大型代码仓库以及多个语言服务器并发运行时，更容易出现这种情况。

​
症状

  • 连接到 WSL 时，Windsurf 明显变慢或卡顿
  • 编辑器经常与 WSL 后端断开连接并尝试重新连接
  • 无论是在进行开发（例如使用 Cascade 时）还是 在编辑器空闲时，都会发生断连
  • Windsurf 崩溃或无响应，需要同时重启 IDE 和 WSL（wsl --shutdown）
  • 即使在拥有 32 GB 以上内存的系统上，WSL 的内存占用也会随时间增长
  • WSL 诊断日志中显示大量 P9 Reply_Rlerror 事件（文件未找到错误）
  • 在 WSL 之外使用 Windsurf 时（例如打开本地 Windows 文件夹），性能表现正常
  • 常见变通方法（重启 WSL、重新安装 Windsurf、增加 .wslconfig 中的内存配置）本身无法解决该问题

​
根本原因

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 如果你从 VS Code 或其他编辑器沿用了一大批对当前项目并不需要的扩展，这种情况就尤其容易发生。

​
解决方案

​
1. 在 WSL 中对 Windsurf 服务器进行干净重装

删除 WSL 中的 Windsurf 服务器目录，下一次连接时由 Windsurf 自动重新安装： 
rm -rf ~/.windsurf-server
然后重新将 Windsurf 连接到 WSL。服务器会自动重新安装。

​
2. 尽量减少已安装的扩展（影响最大）

只为你当前正在处理的代码仓库安装真正需要的扩展。
  • 在连接到 WSL 时，在 Windsurf 中打开 Extensions 面板
  • 检查有哪些扩展安装在 WSL 环境中（不只是本地环境）
  • 禁用或卸载你不需要的扩展——尤其是那些会大量进行文件监控或索引的扩展
在 WSL 中已知存在问题的扩展：
  • Vue (Volar) —— 已确认会通过 9P 桥执行过量的文件索引，即使在非 Vue 项目中也是如此。仅仅卸载这个扩展，就已经为多位用户解决了断连问题。
  • 其他特定框架的语言扩展（Angular、Svelte 等）如果已安装却并非当前工作区所需，也可能表现出类似的行为。
不要假设在本地（非 WSL）环境中运行良好的扩展在 WSL 中也会表现相同。真正的瓶颈是 9P 文件系统桥——在本地无害的扩展，当每一次文件操作都必须跨越协议边界时，就可能变得不稳定。 减少由扩展驱动的文件系统活动，可以直接降低对 9P 桥的压力。

​
3. 优化 WSL 资源限制

在你的 Windows 主机上创建或编辑 %USERPROFILE%\.wslconfig 文件（例如 C:\Users\<YourUser>\.wslconfig），为你的系统设置合适的资源限制： 
[wsl2]
memory=16GB
swap=4GB
processors=4
autoMemoryReclaim=gradual
根据你系统的可用资源调整这些数值。 保存文件后，重新启动 WSL： 
wsl --shutdown
然后重新打开 Windsurf，并再次连接到 WSL。

​
诊断

​
检查 WSL 诊断日志中的 9P 错误

要确认 9P 饱和是否是原因，请收集 WSL 诊断日志： 
wsl --debug-shell
或者收集完整的诊断信息包： 
Invoke-WebRequest -UseBasicParsing "https://aka.ms/wsldiag" -OutFile wsldiag.ps1
.\wsldiag.ps1
在 9P/文件系统日志中查找大量 Reply_Rlerror 事件。出现成千上万（或更多）此类事件通常表明 WSL 内部的扩展或进程正在生成过多的文件系统请求，导致 9P 桥接进程无法及时处理。

​
在什么情况下使用哪种修复方案

  • 如果你在 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）。 添加以下内容： 
[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 内访问网络。