Remote-WSL是Windows用户唯一能兼顾性能、文件互通和调试原生性的VSCode远程开发方案，因其直接复用WSL2进程通信机制，无需SSH配置，终端、调试器、语言服务均在WSL2内原生运行；而Remote-SSH需额外部署sshd、管理端口与密钥，引入网络开销与兼容性问题。
VSCode 远程开发不是“连上服务器就行”，而是要明确用哪种远程模式——对 Windows 用户来说，Remote-WSL 是唯一真正能兼顾性能、文件互通和调试原生性的方案，其他方式（如 SSH）在这里属于绕远路。
为什么必须用 Remote-WSL 而不是 Remote-SSH？
Remote-SSH 本质是走 TCP 连接，哪怕本地跑 WSL2，也得额外配 sshd、开端口、处理密钥和权限。而 Remote-WSL 直接复用 WSL2 的进程通信机制，没有网络栈开销，code . 启动后所有终端、调试器、语言服务都在 WSL2 进程里跑，路径、环境变量、gdb、cmake 全部按 Linux 原生逻辑工作。
常见误操作：
- 在 Windows PowerShell 里执行
code .—— 这会打开 Windows 版 VSCode，根本没进 WSL 环境 - 在 WSL 终端里装了
code命令但没装Remote-WSL扩展 ——code .会失败或回退到本地窗口 - WSL 默认是 WSL1 —— 运行
wsl -l -v看不到VERSION 2，Docker 和 systemd 相关项目直接报错
关键配置项必须手动设对
settings.json 里这几个配置不设，C++/CMake 项目大概率编译失败或跳转失效：
-
"remote.WSL2.distribution": "Ubuntu-22.04"—— 必须和wsl -l -v输出的发行版名完全一致，大小写敏感 -
"terminal.integrated.defaultProfile.linux": "Ubuntu-22.04"—— 防止集成终端默认启动 Windows PowerShell -
"C_Cpp.intelliSenseEngine": "Default"—— 新版 C/C++ 扩展默认用 Tag Parser，对多级include支持差，切回 Default 更稳 - 不要在 Windows 侧的
settings.json里配compileCommands—— 这个路径必须写成 WSL 下的绝对路径，比如"${workspaceFolder}/build/compile_commands.json"
第一次连接卡住？先看 VSCode Server 装在哪
VSCode 第一次通过 Remote-WSL 连接时，会在 WSL 里自动下载并安装 vscode-server，位置固定在：~/.vscode-server。如果卡在 “Installing VS Code Server…”：
- 检查 WSL 是否能访问外网（
curl -I https://update.code.visualstudio.com） - 确认磁盘空间 ——
df -h查/分区，~/.vscode-server占用约 300MB，但解压临时目录需要双倍空间 - 别手动删
~/.vscode-server后重试 —— 可能残留锁文件，应先运行killall -9 node再试code . - 离线环境？提前在外网机器上运行一次
code .，把~/.vscode-server打包带入
CMake 项目 configure 失败的三个高频原因
按 Ctrl+Shift+P → CMake: Configure 没反应，或报 Could not find compiler set in environment variable CC：
- 没在 WSL 里装
build-essential——sudo apt install build-essential是刚需，不是可选 - CMake Tools 扩展没在 WSL 侧启用 —— 点击 VSCode 左下角 ">
-
CMakeLists.txt里用了 Windows 风格路径，比如include_directories("C:/dev/include")—— WSL 里必须用/home/user/dev/include
最易被忽略的一点：WSL2 的 /tmp 默认挂载为 noexec，某些 CMake 生成的临时脚本会因权限拒绝执行；临时解决可加 sudo mount -o remount,exec /tmp，长期方案是在 /etc/wsl.conf 加 [automount] options = "metadata,uid=1000,gid=1000,umask=022,exec"。
