vscode 连接 wsl 必须显式进入 wsl 上下文，否则仍运行在 windows 环境；应使用 ctrl+shift+p 执行 remote-wsl: new window 或点击左下角远程图标，避免直接打开 /mnt/c/ 路径导致终端为 powershell。

VSCode 连接 WSL 开发，不是“能连上就行”，关键在于连接后是否真正在 Linux 环境里运行命令、调用工具链、读写文件——否则只是换了个终端壳子。你遇到的 gcc 找不到、python3 版本不对、调试器挂起、或文件保存后 Windows 侧看不到变更，几乎都源于路径误用、环境错位或扩展未生效。

Remote - WSL 扩展没生效，终端还是 Windows PowerShell

这是最常被忽略的第一步失败点：VSCode 启动后默认仍运行在 Windows 上，即使你装了 Remote - WSL，它也不会自动接管。必须显式进入 WSL 上下文。

• 不要点击“Open Folder…”后直接浏览 C: 或 /mnt/c/ 下的路径——这会以 Windows 模式打开，终端仍是 PowerShell/CMD
• 正确做法是：按 Ctrl+Shift+P 打开命令面板，输入 Remote-WSL: New Window 并回车；或点击左下角状态栏的远程连接图标（显示为“>Open Folder in WSL
• 成功后，窗口右下角应明确显示 WSL: Ubuntu（或你安装的发行版名），且新建终端（Ctrl+`）提示符变成 username@hostname:~$
• 如果仍不生效，检查 VSCode 是否为 Windows 原生版本（非 WSL 内 apt install code 安装的旧版），且 Remote - WSL 扩展已启用（不是禁用或灰色）

项目放在 /mnt/c/ 导致性能差、权限错、Git 异常

WSL 虽能访问 Windows 文件系统，但 /mnt/c/ 是通过 DrvFs 驱动挂载的，I/O 性能比原生 Linux 文件系统低 5–10 倍，且不支持 Linux 文件权限、符号链接、socket 文件等语义。

linux-sysadmin

Linux系统管理专家，覆盖12大模块：用户权限、SSH、存储、网络、systemd、防火墙、日志监控、备份恢复、TLS证书、Ansible、容器、IaC。提供配置、验证、加固、监控、备份、自动化、故障排查、回滚闭环。关键词：useradd、sudo、sshd_config、chmod、SEL...

下载

• 所有开发项目必须存放在 WSL 根文件系统内，例如 ~/projects/myapp 或 /home/username/src
• 避免在 /mnt/c/ 中执行 git clone、npm install、make 等 I/O 密集操作；否则你会遇到 Git 报错 unable to create file: Permission denied，或 Node.js ENOSPC（因 inotify 事件丢失）
• 若需从 Windows 快速打开某项目，可在 WSL 终端中进入其 Linux 路径后执行 code . ——前提是 VSCode 已配置 PATH（安装时勾选了 “Add to PATH”）
• Windows 侧想访问这些文件？用 VSCode 的文件资源管理器直接浏览，或在 Windows 资源管理器地址栏输入 \wsl$Ubuntuhomeusernameprojects

调试 C/C++ 或 Python 时找不到 gdb 或 python3 可执行文件

VSCode 调试器依赖 WSL 环境变量和 PATH 查找工具，但它不会自动继承你在 bashrc 中设置的别名或函数，也不会跨发行版复用 Windows 的安装路径。

• 先在集成终端中手动运行 which gdb 和 which python3，确认它们存在且路径合理（如 /usr/bin/gdb、/usr/bin/python3）
• 若缺失，需在 WSL 中安装对应工具链：sudo apt update && sudo apt install build-essential gdb python3 python3-pip
• 调试配置（.vscode/launch.json）中，miDebuggerPath 必须填绝对路径，不能写 gdb；同理，python 字段应设为 /usr/bin/python3，而非 python
• 注意：WSL 默认不启动 systemd，某些需要服务后台运行的调试场景（如 attach 到守护进程）需额外处理，这不是 VSCode 问题，而是 WSL 运行模式限制

扩展同步失败、设置丢失、插件不工作

VSCode 的 Settings Sync 功能默认只同步“全局设置”，而 Remote - WSL 环境下的扩展、快捷键、代码片段等属于“远程设置”，需单独开启。

• 登录 VSCode 账户后，在 WSL 窗口中点击左下角齿轮 → Turn on Settings Sync → 明确勾选 Extensions、Settings、Keybindings、Snippets
• 部分扩展（如 C/C++、Python）需在 WSL 环境中重新安装——它们会检测当前平台并下载对应语言服务器（如 cpptools-srv Linux 二进制）
• 若扩展报错 “Server failed to start”，常见原因是 WSL 缺少依赖库（如 libxkbcommon0、libsecret-1-0），运行 sudo apt install libxkbcommon0 libsecret-1-0 即可修复
• 不要在 Windows 侧 VSCode 中安装 Remote - WSL 扩展后，再试图在 WSL 终端里用 code --install-extension 手动装——这会导致扩展重复注册、冲突

真正无缝的切换，不在界面是否变蓝，而在你忘记自己正用着 Windows。一旦开始把项目放 /mnt/c/、在 Windows 终端里敲 g++、或以为 code . 总能打开 WSL 环境——那些卡顿、报错和奇怪行为，就全是信号：你还没真正“进去”。