VSCode真正联动WSL2的核心是确保编辑器、调试器、终端、解释器、Git、编译器全部运行在同一文件系统（/home/yourname/）和UTF-8 locale上下文中；必须在WSL终端执行code .，禁用/mnt/c/路径，手动挂载USB设备，并配置wsl.conf元数据选项。
VSCode 要真正联动 WSL2，核心不是“连上”，而是让编辑器进程、调试器、终端、Python 解释器、Git、编译器全部运行在同一个文件系统和用户上下文中——否则你改的代码，idf.py 看不见；设的断点，gdb 找不到源路径；提交的中文日志，git log 显示成 亥。
code . 必须在 WSL 终端里执行，不能在 Windows PowerShell 里敲
这是最常被跳过的一步。你在 Windows 的 CMD/PowerShell 里输入 code .，打开的是 Windows 版 VSCode，它读取的是 C:Users... 下的文件，而你的 gcc、python3、make 全在 WSL 里，路径、权限、环境变量全不匹配。
- 正确流程：先用
wsl或从开始菜单启动 Ubuntu →cd /home/yourname/project→ 再执行code . - 首次执行会自动下载
vscode-server到$HOME/.vscode-server，耗时取决于网络，别关终端 - 成功标志：窗口标题栏显示
WSL: Ubuntu，状态栏右下角出现远程连接图标（地球+小箭头） - 如果提示
command not found，说明 Windows 的code命令没注册进 WSL PATH —— 重装 VSCode 时勾选 “Add to PATH”，或在 Windows PowerShell 中运行code --install-server后执行wsl --shutdown
项目必须放在 /home/yourname/，不能放 /mnt/c/
/mnt/c/ 是 WSL 通过 drvfs 挂载的 Windows 文件系统，不支持 Linux 权限位、inode 一致性、实时 inotify 通知。Git 会丢配置、chmod +x 无效、rsync 同步失败、调试器加载符号路径出错都是因为它。
- 所有开发目录必须建在 WSL 原生路径下，例如：
/home/yourname/myapp、/home/yourname/esp32-projects - Windows 端要访问这些文件？用资源管理器打开
\wsl$Ubuntuhomeyournamemyapp（注意是反斜杠） - VSCode 里不要用 “文件 → 打开文件夹” 去选
/mnt/c/...，而要用命令面板Ctrl+Shift+P→ 输入WSL: Open Folder in WSL，再导航到/home下
locale 和 VSCode 编码必须双锁 UTF-8
WSL 默认 locale 是 C 或空，导致所有底层工具（git、python、bash）按 ASCII 解析字节流，中文直接崩成八进制转义串。这不是 VSCode 显示问题，是整个工具链的解析逻辑错了。
- 检查当前 locale：
locale，若LANG是C或未设置，执行：sudo locale-gen en_US.UTF-8 zh_CN.UTF-8sudo update-locale LANG=en_US.UTF-8 - 重启 WSL：
wsl --shutdown，再重新打开终端，确认locale输出含UTF-8 - VSCode 设置中禁用
files.autoGuessEncoding，并显式设files.encoding为utf8 - 额外加固：编辑
/etc/wsl.conf，加入[automount] options = "metadata,uid=1000,gid=1000,umask=022"，避免挂载 Windows 盘时权限错乱
USB 设备（如 ESP32 串口）需手动挂载，WSL2 不自动暴露
WSL2 默认隔离 USB 总线，idf.py port list 扫不到 /dev/ttyUSB0 是正常现象。这不是驱动问题，是架构限制。
- Windows 端以管理员身份运行：
usbipd wsl list，确认设备 STATE 为Not attached - 记下 BUSID（如
1-1），然后执行：usbipd wsl attach --busid 1-1 - 回到 WSL 终端，运行
ls /dev/tty*，应能看到新增的/dev/ttyACM0或/dev/ttyUSB0 - 每次重启 WSL 后需重新 attach；可写脚本自动执行，但不可设开机自启（usbipd 服务依赖 Windows 用户会话）
- 注意：仅适用于 USB 串口类设备；USB 摄像头、网卡等复杂设备仍受限
真正卡住人的从来不是“怎么连”，而是“连上之后为什么 Git 提交乱码、为什么 Python 断点灰掉、为什么 make 报 no rule to make target”。这些问题的根因几乎都落在路径归属、locale 配置、USB 挂载这三处——它们不报红错，但让整个开发流 silently 失效。
