必须显式进入WSL上下文（如执行Remote-WSL: New Window），确保右下角显示“WSL: Ubuntu”，终端为Linux提示符，项目置于/home/xxx等原生路径，所有工具链在WSL内安装配置，否则仅是Windows编辑器壳子。
VSCode 能通过 WSL 插件实现真正的 Linux 原生开发环境，但前提是必须让 VSCode 的核心（语言服务、调试器、终端、Git）全部运行在 WSL 里，而不是只在 Windows 上打开 /mnt/c/ 下的文件。否则你只是换了个编辑器壳子，gcc 找不到、gdb 启动失败、git 权限报错、make 卡住，全是环境错位导致的。
Remote-WSL 扩展没生效，终端还是 PowerShell
这是最常被跳过的致命一步：装了插件 ≠ 自动接管。VSCode 默认启动后仍在 Windows 上运行，即使你点了“Open Folder…”并选了 /mnt/c/Users/xxx/project，终端依然是 PowerShell，which gcc 返回空，uname 显示 MSYS_NT-10.0。
- 必须显式进入 WSL 上下文：按
Ctrl+Shift+P→ 输入Remote-WSL: New Window→ 回车 - 或点击左下角状态栏的远程连接图标（显示为 “>
Open Folder in WSL”），再选 WSL 发行版（如Ubuntu） - 成功后，窗口右下角应明确显示
WSL: Ubuntu，新建终端（Ctrl+`）提示符变成username@hostname:~$，且uname -s输出Linux - 如果扩展图标是灰色或命令面板搜不到
Remote-WSL，检查是否安装的是 Windows 原生版 VSCode（不是 WSL 里apt install code装的旧版），且扩展已启用（非禁用）
项目路径放在 /mnt/c/ 导致 I/O 和权限异常
WSL 可以读写 Windows 文件系统，但 /mnt/c/ 是 DrvFs 挂载，不支持 Linux 文件语义——没有真实 chmod、无符号链接、inotify 事件丢失、I/O 性能低 5–10 倍。所有开发行为都会出问题。
- 项目必须存放在 WSL 原生路径下，例如：
~/projects/myapp或/home/username/src/hello - 避免在
/mnt/c/中执行git clone、npm install、make等操作；否则会遇到Permission denied、ENOSPC、unable to create file - 若需从 Windows 快速打开某项目：先在 WSL 终端中
cd ~/projects/myapp，再执行code .（前提是安装 VSCode 时勾选了 “Add to PATH”） - Windows 侧访问这些文件？资源管理器地址栏输入
\wsl$Ubuntuhomeusernameprojects，或直接在 VSCode 文件资源管理器里浏览
调试 C/C++ 或 Python 时找不到 gdb 或 python3
VSCode 调试器依赖 WSL 环境变量和 PATH 查找可执行文件，但它不会加载你的 .bashrc 别名，也不会继承 Windows 的 PATH。工具必须真正在 WSL 中可用且在 PATH 里。
- 确保已在 WSL 中安装对应工具：
sudo apt install build-essential gdb（C/C++）、sudo apt install python3 python3-pip python3-debuginfo（Python） - 验证是否在
PATH中：which gdb应返回/usr/bin/gdb，which python3应返回/usr/bin/python3 - 不要在
.bashrc中用alias python=python3，调试器不识别别名；应确保python命令本身可用，或在launch.json中显式指定"python": "/usr/bin/python3" - 如果调试器仍报 “executable not found”，检查 VSCode 是否处于 WSL 上下文（右下角有
WSL: Ubuntu），且终端中能正常运行该命令
扩展没装对位置，Python 或 C/C++ 功能不工作
WSL 扩展把 VSCode 拆成客户端（Windows UI）和服务端（WSL 进程）。扩展也分两类：本地扩展（主题、快捷键）只需装一次；语言/调试类扩展（如 Python、C/C++）必须单独装在 WSL 发行版里。
- 打开 VSCode 后，确认已进入 WSL 上下文（右下角显示
WSL: Ubuntu） - 点击左侧扩展图标 → 在搜索框输入
Python→ 确认看到 “Install on WSL: Ubuntu” 按钮（不是 “Install”）→ 点击安装 - 同理，
C/C++扩展也要在 WSL 上下文中安装，否则 IntelliSense 不识别stdio.h，tasks.json里的gcc路径无效 - 已装在 Windows 的扩展不会自动同步到 WSL；反之亦然。误装在 Windows 侧会导致 “No C/C++ configuration detected” 或 Python 解释器列表为空
最容易被忽略的是：你以为打开了 WSL，其实只是打开了一个带 Linux 图标的 Windows 窗口。真正生效的标志只有两个——右下角明确显示 WSL: Ubuntu，且终端里 pwd 输出的是 /home/xxx/... 而不是 /mnt/c/...。其他所有问题，几乎都源于这一步没走对。
