WSL2 + VSCode 远程开发是目前 Windows 上最接近原生 Linux 开发体验的方案，但关键在于让 VSCode 完全运行于 WSL2 环境：必须通过 Remote-WSL 插件以“WSL: New Window”启动，项目路径限于 /home/user/ 等 WSL 内部目录，tasks/launch.json 配置须使用 WSL 绝对路径且避免 Windows 工具链混用。
直接说结论：WSL2 + VSCode 远程开发是目前 Windows 上最接近原生 Linux 开发体验的方案，但默认配置下 git、node、python 等工具链容易错用 Windows 版本，导致命令失败或环境不一致——关键不是连上 WSL2，而是让 VSCode 完全“信任”并“只用” WSL2 里的环境。
VSCode 必须通过 Remote-WSL 插件启动，不能在 Windows 下打开 WSL 路径
常见错误是：在 Windows 文件资源管理器里右键 WSL 路径（如 \wsl$\Ubuntu\home\user\project），再用 VSCode 打开。这样 VSCode 仍运行在 Windows 进程中，Terminal 默认调用的是 Windows PowerShell/CMD，which git 返回的是 C:\Program Files\Git\bin\git.exe，而不是 /usr/bin/git。
正确做法：
- 确保已安装官方插件
Remote - WSL（ID：ms-vscode-remote.remote-wsl） - 关闭所有 VSCode 窗口，从 Windows 启动 VSCode 时不要打开任何文件夹，先按
Ctrl+Shift+P→ 输入WSL: New Window→ 选择目标发行版（如Ubuntu-22.04） - 再在该窗口中用
File → Open Folder…，路径必须是 WSL 内部路径，例如/home/user/myapp（不是\wsl$…） - 此时状态栏左下角会显示
WSL: Ubuntu-22.04，且新建终端自动是bash，which python指向/usr/bin/python3
tasks.json 和 launch.json 必须限定在 WSL 环境内执行
即使终端正常，VSCode 的构建任务（tasks.json）或调试配置（launch.json）若写死绝对路径或未指定 shell，仍会调用 Windows 工具。典型表现是：npm run build 报错 command not found，或 Python 调试器找不到 venv 中的解释器。
解决要点：
Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。
-
tasks.json中必须设置"type": "shell"，避免写C:\Users\类路径；命令直接写"npm install"即可，由 WSL 终端环境执行 -
launch.json中的python.defaultInterpreterPath应设为/home/user/.pyenv/versions/3.11.9/bin/python这类 WSL 内部路径，而非C:\Users\… - 如果用
preLaunchTask，确认该 task 的group是build，且isBackground配合problemMatcher正确，否则调试器会卡住
项目路径必须放在 WSL 文件系统内，不能挂载 Windows 盘
把项目放在 /mnt/c/Users/xxx/project（即 Windows C: 盘映射目录）看似方便，实则埋雷：
- 文件权限丢失：Windows 不支持 Linux 的
chmod，git无法正确标记可执行脚本 - 行尾符混乱：Windows 默认 CRLF，WSL 期望 LF，
git status反复提示改动 - 性能断崖：I/O 经过 9P 协议转发，
npm install或apt update速度下降 3–5 倍 - 符号链接失效：WSL 内创建的 symlink 在
/mnt/c下被转为 Windows 快捷方式，破坏构建逻辑
正确位置只有两个：/home/user/project（推荐）或 /opt/project（需 sudo）。初始化项目务必在 WSL 终端中执行：cd /home/user && mkdir myapp && cd myapp。
WSL2 内核版本和发行版名称必须合规，否则 Remote-WSL 插件无法识别
VSCode Remote-WSL 插件默认只扫描 Ubuntu、Debian、KaliLinux 等白名单名称的发行版。如果你用 wsl --install -d Ubuntu-24.04 或手动导入了 my-ubuntu，插件可能根本看不到它。
检查与修复步骤：
- 在 PowerShell 中运行
wsl -l -v，确认状态为Running且名称是Ubuntu这类标准名；如果不是，用wsl --set-default <code>your-distro-name</code> - 内核版本太低（如
5.4.x）会导致dockerd启动失败，现象是sudo dockerd卡住或报错kernel version not supported；需单独升级内核：下载微软官网wsl_update_x64.msi，安装后执行wsl --shutdown再重启发行版，验证uname -r输出是否 ≥5.10 - 若插件提示
command 'remote-wsl.reopenInWsl' not found，不是插件没装，而是 VSCode 没识别到 WSL2 实例——请关闭所有 VSCode 窗口，再从 PowerShell 执行code .（注意是点号），而非从 VSCode 内部触发命令
真正卡住人的地方从来不是“怎么装”，而是“怎么让 VSCode 彻底放弃 Windows 身份，老老实实当一个 WSL 进程”。只要路径、终端、任务、调试器四者全部落在 WSL 文件系统和 PATH 里，剩下的就是写代码的事了。
