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 Linux Hardware Debug

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
• 内核版本太低（如 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 里，剩下的就是写代码的事了。