VSCode连接WSL2子系统详细教程 - 在Windows中流畅开发Linux项目-VSCode-PHP中文网

vscode 可直接连接 wsl2，无需 ssh；需安装 remote - wsl 扩展，通过 ctrl+shift+p 运行 wsl: new window，再用 wsl$ 路径打开项目；code 命令需在 windows 端注册并重启 wsl2；须配置 utf-8 locale、禁用 autoguessencoding、避免使用 /mnt/c/ 路径开发。

vscode连接wsl2子系统详细教程 - 在windows中流畅开发linux项目

VSCode 能直接连上 WSL2，不需要额外装 SSH 服务，也不用改配置文件——只要 WSL2 已启动且 VSCode 是 Windows 版本（非 Web 版），点一下就能进。

怎么从 VSCode 打开 WSL2 的项目目录

不是靠“打开文件夹”选 /home/xxx 这种路径，WSL2 的文件系统在 Windows 下是挂载出来的，但直接访问容易出权限或换行符问题。正确做法是用 VSCode 内置的远程机制。

确保已安装 Remote - WSL 扩展（微软官方，名字带“WSL”，别装错成“Remote SSH”）
在 Windows 上启动 VSCode（不是从 WSL 里用 code 命令启动）
按 Ctrl+Shift+P，输入 WSL: New Window，回车——这时新窗口左下角会显示 WSL: Ubuntu（或你装的发行版名）
再用 File → Open Folder，路径栏里直接输入 \wsl$Ubuntuhomeyournameproject（Windows 路径格式），或者点左侧“Explorer”里的“WSL”项展开后找目录

为什么 `code .` 在 WSL2 终端里没反应或报错

这是最常卡住的地方：你在 WSL2 的 bash 里执行 code .，结果提示“command not found”或弹出 Windows 版 VSCode 但不加载当前目录。根本原因是 code 命令没被正确注册到 WSL2 的 PATH。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

首次使用前必须在 Windows 端 VSCode 中执行一次 Command Palette → Shell Command: Install 'code' command in PATH
执行完后重启 WSL2：wsl --shutdown，再重新打开终端
检查是否生效：which code 应该返回 /usr/bin/code；如果还是找不到，说明 WSL2 没读到 Windows 注册的 shell wrapper，可手动加一行到 ~/.bashrc：export PATH="$PATH:/mnt/c/Users/xxx/AppData/Local/Programs/Microsoft VS Code/bin"（路径按你实际安装位置调整）

编辑器里中文乱码、Git 提交日志显示异常

WSL2 默认 locale 是 C 或 POSIX，没有 UTF-8 支持，VSCode 后台调用的 Git、Python、Shell 工具全会出问题，比如 git log 显示 中文 这种八进制编码。

在 WSL2 里编辑 /etc/wsl.conf（如不存在就新建），加入：

[boot]
command = "sudo /usr/bin/locale-gen en_US.UTF-8 zh_CN.UTF-8"
<p>[user]
default = yourusername</p><p>[automount]
enabled = true
options = "metadata,uid=1000,gid=1000,umask=022,fmask=111"</p>

然后 wsl --shutdown，重启终端，再运行 locale -a | grep utf8 确认有 zh_CN.utf8

VSCode 设置里关掉 files.autoGuessEncoding，强制设为 utf8，避免某些文件误判编码

调试 Python/Node.js 时断点不命中、终端输出不刷新

本质是 WSL2 的文件系统跨层同步延迟 + VSCode 调试器对符号路径解析不准。尤其当你在 Windows 文件资源管理器里改了代码，再切回 VSCode 调试，经常断点灰掉或跳过。

所有开发工作务必在 \wsl$ 挂载路径下进行，**不要**把项目放在 /mnt/c/xxx（即 Windows 盘映射路径）——那里是通过 drvfs 驱动访问的，inode 和权限模拟不完整
Python 调试时，在 launch.json 里显式指定 "justMyCode": true 和 "console": "integratedTerminal"，避免调试器混淆路径
Node.js 项目用 nvm 安装的版本，确保 which node 返回的是 WSL2 内部路径（如 /home/xxx/.nvm/versions/node/v18.18.2/bin/node），而不是 /mnt/c/ 下的 Windows 版本

真正麻烦的不是连不上，而是连上了却用得别扭——比如 Git 提交用中文写日志，结果日志在 VSCode 的 Source Control 面板里显示为空白方块；又比如改完一个 Python 文件，print() 输出还卡在旧值，其实是调试器缓存了旧字节码。这些都不是配置漏了，是 WSL2 和 VSCode 在路径、编码、进程生命周期上咬合得不够紧。