本文档翻译并整理自 Visual Studio Code Remote Development in WSL 教程，用于记录如何启用 Windows Subsystem for Linux（WSL），并通过 VS Code 的 WSL extension 在 Linux 环境中进行开发。

注意： 本文聚焦 VS Code + WSL 的开发体验。WSL 安装方式、VS Code 扩展能力和界面细节可能随版本变化，使用前以 VS Code 和 Microsoft 官方文档为准。本文最后核对日期为 2026-05-26。

适用场景

  • 想在 Windows 上使用 Linux 工具链开发。
  • 想让 VS Code 的终端、语言扩展、调试器都运行在 WSL 中。
  • 不想在 Windows 和 Linux 两边重复安装 Python、Node、编译器等开发工具。
  • 希望项目路径、运行时、依赖和调试环境保持一致。

前置条件

你需要先安装 Visual Studio Code。

安装 WSL Extension

VS Code 的 WSL extension 可以让 VS Code 连接到 Windows Subsystem for Linux，并在 WSL 环境中运行编辑、终端、扩展和调试能力。

安装完成后，VS Code 左下角状态栏会出现 Remote Status bar item。它可以快速显示当前 VS Code 运行在本地还是远程环境中。点击该状态栏项，可以打开 WSL extension 的相关命令。

启用 WSL

Windows Subsystem for Linux（WSL）是 Windows 的 Linux 兼容开发环境。当前 Microsoft 官方推荐优先使用 wsl --install 一次性安装 WSL 和默认 Linux 发行版。

以管理员身份打开 PowerShell：

1
wsl --install

如果需要指定发行版，可以先查看可用列表：

1
2
wsl --list --online
wsl --install -d Ubuntu

下面的 Windows Features 和旧 PowerShell 命令更适合旧版本 Windows 或需要手动排障时参考。

通过 Windows Features 启用

在 Windows 搜索栏输入 features，打开 Turn Windows Features on and off。

在列表中找到并勾选：

1
Windows Subsystem for Linux

点击 OK 后，系统会提示重启 Windows。

通过 PowerShell 启用

也可以以管理员身份打开 PowerShell，执行：

1
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

命令执行完成后，系统会提示重启 Windows。

检查 WSL 是否启用

重启 Windows 后，打开 Command Prompt，执行：

1
wsl

如果 WSL 已启用但尚未安装 Linux 发行版，系统会提示需要安装发行版。

安装 Linux 发行版

可以从 Microsoft Store 安装 WSL 的 Linux 发行版，也可以在 Windows 搜索栏中搜索想安装的发行版，例如 Ubuntu。

安装流程：

  1. 选择 Linux 发行版，例如 Ubuntu。
  2. 点击 Install。
  3. 安装完成后点击 Launch。
  4. 首次启动会打开 Linux 终端并完成初始化。
  5. 根据提示创建 Linux 用户名和密码。

完成后，你就拥有了一个运行在 Windows 上的 Linux 环境。

Python 开发示例

如果 WSL 中还没有安装 Python，可以执行：

1
2
sudo apt update
sudo apt install python3 python3-pip

验证版本：

1
python3 --version

创建一个最小的 Hello World 项目：

1
2
3
mkdir helloWorld && cd helloWorld
echo 'print("hello from python on ubuntu on windows!")' >> hello.py
python3 hello.py

在 WSL 这样的远程 Linux 环境中，这个 Linux 发行版可以理解为一台没有图形界面的本地 Linux 机器。你可以在终端里用 Vim 编辑，也可以通过 Windows 的 \\wsl$ 挂载路径访问文件。

但直接在 Windows 侧编辑 WSL 文件会带来一个问题：Python runtime、pip、conda package 等开发工具安装在 Linux 发行版中，而不是 Windows 中。如果你在 Windows 侧编辑 Python 文件，除非 Windows 也安装同样的 Python 开发栈，否则无法正确运行和调试。

这会违背 WSL 的核心价值：让 Linux 发行版作为隔离的开发环境，并把语言工具、运行时、依赖都放在 Linux 里。

在 WSL 中运行 VS Code

在 WSL 终端中进入 helloWorld 目录，执行：

1
code .

. 表示让 VS Code 打开当前目录。

如果你使用的是 VS Code Insiders，需要执行：

1
code-insiders .

如果 code . 无法运行，可能需要重启终端，或安装 VS Code 时没有把 code 加入 PATH。

第一次连接时，VS Code 会在 Linux 侧安装一个小型 VS Code Server。Windows 桌面版 VS Code 会和这个 Linux 侧 server 通信。后续语言扩展也会安装并运行在 WSL 环境中，从而使用 WSL 中安装的工具链和框架，而不是 Windows 侧工具链。

连接完成后，VS Code 会打开 helloWorld 文件夹。你可能会看到 VS Code 正在连接 WSL 的通知，也可能被要求允许基于 Node.js 的 server 访问。

此时，把鼠标悬停到 hello.py 上时，看到的应该是 Linux 路径，而不是 Windows 路径。

集成终端

在 VS Code 中打开：

1
Terminal > New Terminal

也可以使用你本机 VS Code 绑定的终端快捷键。

打开后，你会得到一个运行在 WSL 中的新 bash shell。VS Code 虽然桌面窗口运行在 Windows 上，但终端上下文是在 Linux 中。

可以通过左下角状态栏确认连接状态，例如：

1
WSL: Ubuntu

编辑与调试

安装 Python Extension

打开 hello.py 后，VS Code 可能会推荐安装 Microsoft Python extension。安装后可以获得 Python 的补全、跳转、调试等能力。

重新打开 Extensions 视图，可以看到类似下面的分组：

1
WSL: Ubuntu - Installed

这表示扩展安装在 WSL 侧。也就是说，Python extension 会使用 WSL 中的 Python、pip、lint 工具和调试环境。

如果 VS Code 提示没有安装 pylint 这类 linter，可以按提示安装。linter 用于在源码中展示错误和警告。

安装完成后，编辑 Python 文件时会获得语法高亮、补全、诊断和 lint 提示。

调试 Python 文件

调试步骤：

  1. 打开 hello.py。
  2. 在第 1 行左侧 gutter 点击，设置断点。
  3. 按 VS Code 的启动调试快捷键，通常是 F5。
  4. 当 VS Code 询问如何运行时，选择 Python File。
  5. 程序启动后会命中断点。

命中断点后，可以查看变量、添加 watch、查看调用栈，并使用 Step Over 等调试操作继续执行。输出会显示在 Debug Console 中。

这时你获得的是完整 VS Code 开发体验，但运行时和调试环境来自 WSL 中的 Linux。

打开其他 WSL 文件夹

如果想打开 WSL 中的另一个文件夹，可以在 VS Code 中选择：

1
File > Open Folder

此时出现的是 Linux 文件系统的文件夹选择器，而不是 Windows 文件系统选择器。

如果想切换回 Windows 本地文件系统，可以选择：

1
Show Local

这样会回到标准 Windows 文件打开对话框。

结束 WSL 连接

如果想结束当前 WSL 远程会话，并回到本地 VS Code，可以选择：

1
File > Close Remote Connection

常见检查

确认 VS Code 正在 WSL 中运行

可以检查：

  • 左下角状态栏显示 WSL: <distro>。
  • 终端路径是 /home/...，而不是 C:\...。
  • 执行 pwd 后显示 Linux 路径。
  • 执行 python3 --version 使用的是 WSL 中的 Python。

确认扩展安装在 WSL 侧

打开 Extensions 视图，检查是否有：

1
WSL: Ubuntu - Installed

语言扩展应安装到 WSL 侧，这样它们才能使用 Linux 环境中的解释器、包管理器和依赖。

不要混用 Windows 与 WSL 工具链

推荐原则：

  • 源码放在 WSL 文件系统，例如 ~/code/<project> 或 ~/workspace/<project>。
  • Python、Node、Java 等开发工具安装在 WSL 中。
  • VS Code 通过 WSL extension 打开 WSL 文件夹。
  • 集成终端、调试器、语言扩展都使用 WSL 环境。

不要长期把主力项目放在 /mnt/c/... 下开发，也不要让 Windows 的 Python/Node/Java 处理 WSL 项目依赖。

后续 Remote Development 扩展

除了 WSL extension，VS Code 还有其他 Remote Development 扩展：

参考链接

迭代记录

  • 2026-05-26：按 Microsoft WSL install 文档和 VS Code WSL 教程复核安装入口；补充 wsl --install / wsl --list --online / wsl --install -d Ubuntu，保留旧 Windows Features 和 PowerShell 启用方式作为兼容排障参考。
  • 2026-05-15：初始化 VS Code WSL 远程开发指南，整理 WSL extension、WSL 发行版、Python 示例、调试和工具链边界。