Remote-WSL扩展未安装或未启用会导致VSCode状态栏不显示WSL标识；必须在WSL终端中执行code .启动项目，且调试器路径、Git配置等均需指向WSL内部环境。
WSL扩展没装或没启用，Remote-WSL 按钮不出现
VSCode 本身不自带 WSL 支持，必须通过官方扩展 Remote-WSL 激活远程开发能力。没装它，所有后续配置都无效。
安装路径很直接：打开 VSCode → 左侧扩展图标（或 Ctrl+Shift+X）→ 搜索 Remote-WSL → 点击“Install”。注意选微软官方发布的那个（Publisher 是 Microsoft），别误装第三方仿名插件。
装完后重启 VSCode（不是仅重载窗口），再打开任意文件夹，状态栏右下角应该出现 WSL: Ubuntu（或你实际发行版名）——这是真正生效的标志。如果没出现，大概率是 WSL 本身没跑起来，先在 Windows 终端里执行 wsl -l -v 确认有运行中的发行版。
用 code . 命令在 WSL 中打开项目，而不是在 Windows 下双击启动
很多人习惯在 Windows 文件资源管理器里双击 VSCode 图标打开项目，结果编辑器还是运行在 Windows 环境下，PATH、编译器、依赖全不对。正确做法是：进入 WSL 终端（比如 Ubuntu），cd 到你的项目目录，然后运行 code .。
这个命令会触发 Remote-WSL 扩展，在 WSL 中拉起一个轻量服务，并把 VSCode 前端连接过去。此时所有终端、调试、任务都默认走 WSL 环境。
常见误区：
-
code .必须在 WSL 的 shell 里执行，不能在 Windows PowerShell 或 CMD 里跑 - 如果提示
command not found: code，说明 VSCode 没把 server 脚本注入 WSL PATH，运行一次echo 'export PATH="$PATH:/mnt/c/Users/xxx/AppData/Local/Programs/Microsoft VS Code/bin"' >> ~/.bashrc && source ~/.bashrc（路径按你本地 VSCode 安装位置调整） - 项目路径建议放在 WSL 文件系统里（如
/home/username/project），避免跨 /mnt/c 访问 Windows 文件，否则文件监控、符号链接、权限等行为异常
调试 C/C++ 时 launch.json 的 miDebuggerPath 必须指向 WSL 内路径
即使 VSCode 已连上 WSL，C/C++ 扩展默认仍可能试图调用 Windows 下的 gdb.exe，导致调试失败或报错 Unable to start debugging. Cannot launch program...。
Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。
解决办法是在项目根目录的 .vscode/launch.json 中显式指定调试器路径：
{
"version": "0.2.0",
"configurations": [
{
"name": "gdb (WSL)",
"type": "cppdbg",
"request": "launch",
"program": "${fileDirname}/${fileBasenameNoExtension}",
"args": [],
"stopAtEntry": false,
"cwd": "${fileDirname}",
"environment": [],
"externalConsole": false,
"MIMode": "gdb",
"miDebuggerPath": "/usr/bin/gdb",
"setupCommands": [...]
}
]
}
关键点：
-
miDebuggerPath值必须是 WSL 内部路径（如/usr/bin/gdb），不能写/mnt/c/...或 Windows 风格路径 - 确保 WSL 中已安装
gdb：sudo apt update && sudo apt install gdb - 如果用
clang++编译，也得确认 WSL 里装了对应工具链，Windows 下的 LLVM 不会被自动复用
Git 提交时用户名和邮箱未继承 WSL 配置，提交记录显示为 Windows 用户
VSCode 在 WSL 模式下仍可能读取 Windows 的 Git 全局配置（%USERPROFILE%\.gitconfig），导致 commit 作者信息错乱，尤其当你在 WSL 和 Windows 两端混用 Git 时更明显。
最稳妥的做法是：在 WSL 终端中单独配置 WSL 的 Git 用户信息，并禁用 Windows 配置的干扰：
- 执行
git config --global user.name "Your Name"和git config --global user.email "you@example.com"（在 WSL 终端里） - 检查是否生效：
git config --list --show-origin，确认user.name和user.email来自/home/username/.gitconfig，而非file:C:/Users/... - 如果看到 Windows 路径优先级更高，可临时禁用：
git config --global core.systemconfig false（不推荐长期关，只用于排障）
这个细节容易被忽略，但直接影响协作时的提交可信度和 GitHub/GitLab 账户绑定。
WSL 开发真正的复杂点不在安装，而在环境归属感的切换——VSCode 界面在 Windows 上，但所有底层行为必须彻底“下沉”到 WSL 语境里。路径、工具链、配置、甚至 shell 初始化逻辑，一旦有一环还粘着 Windows，问题就会以各种奇怪方式冒出来。
