VS Code 连接 WSL2 Linux 环境（教学版）

前置要求：已完成 WSL2 安装（参考「WSL2 搭建 Linux 开发环境」教程），且 VS Code 已安装在 Windows 系统中。
核心优势：在 Windows 下用 VS Code 操作 Linux 环境，兼顾 Windows 易用性和 Linux 开发环境。

一、步骤 1：安装 WSL 扩展（核心）

打开 VS Code，点击左侧边栏「扩展」图标（快捷键 Ctrl+Shift+X）；
在搜索框输入 WSL，找到微软官方的「WSL」扩展（作者：Microsoft，下载量最高）；
点击「安装」，安装完成后无需重启 VS Code（扩展自动生效）。

扩展作用：实现 VS Code 与 WSL2 的通信，让 VS Code 能识别并连接 WSL 环境。

二、步骤 2：连接 WSL2 环境（3种方式，任选其一）

方式 1：从 VS Code 直接连接（推荐）

打开 VS Code，按下快捷键 Ctrl+Shift+P 打开「命令面板」；
输入 WSL: Connect to WSL，回车执行；
在弹出的列表中选择已安装的 WSL 发行版（如 Ubuntu-22.04）；
等待几秒，VS Code 左下角会显示「WSL: Ubuntu」，表示连接成功。

方式 2：从 WSL 终端启动 VS Code

打开 WSL2 终端（Ubuntu），进入要开发的目录（如 cd ~/projects）；
执行命令 code .（注意末尾的点，表示打开当前目录）；
VS Code 会自动启动并连接到 WSL 环境，同时打开该目录。

方式 3：通过远程资源管理器连接

安装「Remote - Explorer」扩展（微软官方）；
点击左侧边栏「远程资源管理器」图标；
在「WSL Targets」下找到你的 Ubuntu 发行版，右键选择「Connect to WSL in New Window」；
新窗口会自动连接到 WSL 环境。

验证连接成功：
1. VS Code 左下角显示「WSL: 发行版名称」；
2. 打开终端（Ctrl+`），终端提示符为 Linux 风格（如 username@DESKTOP:~$）；
3. 新建文件，保存路径为 /home/username/（Linux 路径）。

三、步骤 3：安装 Linux 开发扩展（按需）

连接 WSL 后，安装的扩展分为「Windows 扩展」和「WSL 扩展」，需为 WSL 安装开发所需扩展：

在 VS Code 扩展面板中，已安装的扩展右侧会显示「Install in WSL: Ubuntu」；
为 WSL 安装以下常用扩展（以 C++ 开发为例）：
- C/C++（微软官方，语法高亮/调试/编译）；
- CMake（CMake 配置支持）；
- CMake Tools（CMake 编译调试）；
- Code Runner（快速运行代码）；
- Chinese (Simplified)（中文语言包，可选）。

注意：扩展需分别安装到 Windows 和 WSL 环境，仅安装在 Windows 下无法在 WSL 中使用。

四、步骤 4：实战测试（编写并运行 C++ 代码）

在 WSL 中新建目录：mkdir ~/cpp-demo && cd ~/cpp-demo；
在 VS Code 中打开该目录（code .）；
新建文件 main.cpp，输入以下代码：

#include <iostream>
using namespace std;

int main() {
    cout << "Hello WSL2!" << endl;
    cout << "当前环境：" << __linux__ ? "Linux (WSL2)" : "Windows" << endl;
    return 0;
}

打开 VS Code 终端（Ctrl+`），执行编译命令：g++ main.cpp -o demo；
运行程序：./demo；
终端输出 Hello WSL2! 当前环境：Linux (WSL2)，说明环境正常。

五、常见问题与排查（教学重点）

问题 1：VS Code 提示「无法连接到 WSL」
排查方案：
1. 确认 WSL2 已正常启动（打开 Ubuntu 终端能正常使用）；
2. 以管理员身份重启 VS Code；
3. 执行命令 wsl --shutdown 关闭 WSL，重新启动后再连接。

问题 2：code . 命令提示「找不到」
排查方案：
1. 在 VS Code 中按下 Ctrl+Shift+P，输入 Shell Command: Install 'code' command in PATH；
2. 执行该命令后，重启 WSL 终端即可。

问题 3：代码编译失败（提示 gcc 未找到）
排查方案：
1. 在 WSL 终端执行 gcc --version，确认是否安装；
2. 未安装则执行 sudo apt install gcc g++ -y 安装。

问题 4：中文乱码
排查方案：
1. 在 VS Code 中按下 Ctrl+, 打开设置，搜索 files.encoding；
2. 设置为 UTF-8；
3. 在 WSL 终端执行 export LC_ALL=zh_CN.UTF-8。

六、实用技巧（教学拓展）

文件互访：Windows 路径在 WSL 中为 /mnt/c/Users/你的用户名/，WSL 路径在 Windows 中为 \\wsl$\Ubuntu；
断点调试：安装 C/C++ 扩展后，可直接在 VS Code 中设置断点调试 Linux 下的代码；
切换环境：点击 VS Code 左下角「WSL: Ubuntu」，可快速断开/切换 WSL 环境；
同步设置：安装「Settings Sync」扩展，同步 Windows 和 WSL 中的 VS Code 设置。

← 返回我的主页