WSL 2 远程开发连接死锁故障复盘与解决方案

1. 环境背景

• OS: Windows 10/11
• 子系统: WSL 2 (Ubuntu 24.04)
• 编辑器: Cursor (或 VS Code)
• 开发者职级: Senior (资深工程师)

2. 故障描述

• 核心现象： Cursor 在客户端更新版本后，尝试连接 WSL 失败，界面长久卡在 Opening Remote... 或 Setting up WSL Distro。
• 次生现象： 即使在 WSL 终端手动输入 cursor . 触发安装，安装完成后 UI 界面依然不自动跳转，维持“转圈”状态。

3. 根本原因排查 (Root Cause Analysis)

1. Commit ID 强制对齐： 客户端升级后，必须在 WSL 内部重新部署对应的 cursor-server，由于跨境网速受限（约 160KB/s），导致静默下载过程极其漫长，被误认为卡死。
2. 僵尸进程冲突 (关键原因)： 之前由于网络波动或重复唤起，导致后台残留了多个 cursor-server 进程。新连接请求尝试绑定通信端口时，旧进程拒绝释放，导致“握手死锁”。
3. VHDX 磁盘膨胀： WSL 虚拟硬盘（.vhdx）只增不减的特性导致 D 盘空间持续缩小，若空间不足会导致解压失败。

4. 解决方案 (Step-by-Step)

第一步：物理清理残留进程 (一剑封喉)

这是解决“一直在连接中”最有效的手段。

# 在 Ubuntu 终端执行，强行杀死所有残留的服务端进程
killall -9 cursor-server 2>/dev/null