尝试以扩展 VS Code 中的代理模式！

在 WSL 中开发

Visual Studio Code WSL 扩展允许你直接在 VS Code 中将 适用于 Linux 的 Windows 子系统 (WSL) 用作你的全职开发环境。你可以在基于 Linux 的环境中进行开发，使用 Linux 特定的工具链和实用程序，并从舒适的 Windows 环境中运行和调试你的基于 Linux 的应用程序。

该扩展直接在 WSL 中运行命令和其他扩展，这样你就可以编辑位于 WSL 或已挂载的 Windows 文件系统（例如 /mnt/c）中的文件，而无需担心路径问题、二进制兼容性或其他跨操作系统挑战。该扩展将在 WSL 中安装 VS Code Server；该服务器独立于 WSL 中任何现有的 VS Code 安装。

WSL Architecture

这使得 VS Code 能够提供本地质量的开发体验——包括完整的 IntelliSense（自动完成）、代码导航和调试——无论你的代码托管在哪里。

入门

注意：阅读本主题后，你可以开始学习入门级 WSL 教程。

安装

要开始，你需要

  1. 安装 适用于 Linux 的 Windows 子系统 以及你喜欢的 Linux 发行版。

    注意：WSL 1 对于某些类型的开发确实存在一些已知限制。此外，由于扩展中本机源代码中的 glibc 依赖项，在 Alpine Linux 中安装的扩展可能无法工作。有关详细信息，请参阅远程开发和 Linux 文章。

  2. 在 Windows 端（而不是 WSL 中）安装 Visual Studio Code。

    注意：在安装过程中，当提示你选择其他任务时，请务必勾选添加到 PATH 选项，这样你就可以使用 code 命令轻松地在 WSL 中打开文件夹。

  3. 安装 WSL 扩展。如果你计划在 VS Code 中使用其他远程扩展，你可以选择安装 远程开发扩展包。

打开远程文件夹或工作区

从 WSL 终端

在 VS Code 中打开适用于 Linux 的 Windows 子系统中的文件夹与从命令提示符或 PowerShell 中打开 Windows 文件夹非常相似。

  1. 打开一个 WSL 终端窗口（使用开始菜单项或从命令提示符/PowerShell 中键入 wsl）。

  2. 导航到你想在 VS Code 中打开的文件夹（包括但不限于 Windows 文件系统挂载，如 /mnt/c）

  3. 在终端中键入 code .。第一次执行此操作时，你应该会看到 VS Code 正在获取在 WSL 中运行所需的组件。这应该只需要很短的时间，并且只需要一次。

    注意：如果此命令不起作用，你可能需要重新启动终端，或者在安装 VS Code 时未将其添加到路径中。

  4. 片刻之后，将出现一个新的 VS Code 窗口，你将看到 VS Code 正在 WSL 中打开文件夹的通知。

    WSL Starting notification

    VS Code 现在将继续在 WSL 中配置自身，并随时向你更新进度。

  5. 完成后，你现在会在左下角看到 WSL 指示器，你就可以像往常一样使用 VS Code 了！

    WSL Status Bar Item

就是这样！你在此窗口中执行的任何 VS Code 操作都将在 WSL 环境中执行，从编辑和文件操作到调试、使用终端等等。

从 VS Code

或者，你可以直接从 VS Code 中打开 WSL 窗口

  1. 启动 VS Code。
  2. 按 F1，选择WSL: 连接到 WSL 用于默认发行版，或WSL: 使用发行版连接到 WSL 用于特定发行版。
  3. 使用文件菜单打开你的文件夹。

如果你已经打开了一个文件夹，你也可以使用WSL: 在 WSL 中重新打开文件夹命令。系统将提示你选择要使用的发行版。

如果你在 WSL 窗口中并想在本地窗口中打开当前输入，请使用WSL: 在 Windows 中重新打开。

从 Windows 命令提示符

要直接从 Windows 提示符打开 WSL 窗口，请使用 --remote 命令行参数

code --remote wsl+<发行版名称> <WSL 中的路径>

例如：code --remote wsl+Ubuntu /home/jim/projects/c

我们需要猜测输入路径是文件还是文件夹。如果它有文件扩展名，则将其视为文件。

要强制打开文件夹，请在路径中添加斜杠或使用

code --folder-uri vscode-remote://wsl+Ubuntu/home/ubuntu/folder.with.dot

要强制打开文件，请添加 --goto 或使用

code --file-uri vscode-remote://wsl+Ubuntu/home/ubuntu/fileWithoutExtension

使用 Git

如果你在 WSL 和 Windows 中使用同一个存储库，请务必设置一致的行尾。有关详细信息，请参阅提示和技巧。

你还可以通过配置 WSL 使用 Windows Git 凭据管理器来避免密码。有关详细信息，请参阅提示和技巧。

管理扩展

VS Code 在以下两个位置之一运行扩展：本地 UI/客户端侧，或 WSL 中。虽然影响 VS Code UI 的扩展（如主题和代码片段）安装在本地，但大多数扩展将驻留在 WSL 中。

如果你从“扩展”视图安装扩展，它将自动安装在正确的位置。安装后，你可以根据类别分组来判断扩展的安装位置。将有一个本地 - 已安装类别和一个用于 WSL 的类别。

Workspace Extension Category

Local Extension Category

注意：如果你是扩展作者，并且你的扩展无法正常工作或安装在错误的位置，请参阅支持远程开发了解详细信息。

实际上需要远程运行的本地扩展将在本地 - 已安装类别中显示为灰色和禁用。选择安装以在你的远程主机上安装扩展。

Disabled Extensions w/Install Button

你还可以通过转到“扩展”视图并使用本地 - 已安装标题栏右侧的云按钮选择在 WSL 中安装本地扩展：{名称}来安装 WSL 中所有本地安装的扩展。这将显示一个下拉菜单，你可以在其中选择要在 WSL 实例中安装的本地安装扩展。

Install all extensions

在 WSL 中打开终端

从 VS Code 在 WSL 中打开终端很简单。一旦文件夹在 WSL 中打开，你在 VS Code 中打开的任何终端窗口（终端 > 新建终端）都将自动在 WSL 中运行，而不是在本地运行。

你还可以使用此终端窗口中的 code 命令行执行多项操作，例如在 WSL 中打开新文件或文件夹。键入 code --help 查看命令行中可用的选项。

Using the code CLI

在 WSL 中调试

一旦你在 WSL 中打开了一个文件夹，你就可以像在本地运行应用程序时一样使用 VS Code 的调试器。例如，如果你在 launch.json 中选择了一个启动配置并开始调试（F5），应用程序将在远程主机上启动并将调试器附加到它。

有关在 .vscode/launch.json 中配置 VS Code 调试功能的详细信息，请参阅调试文档。

WSL 特定设置

当你在 WSL 中打开文件夹时，VS Code 的本地用户设置也会被重用。虽然这保持了你的用户体验的一致性，但你可能希望在本地机器和 WSL 之间改变其中一些设置。幸运的是，一旦你连接到 WSL，你还可以通过从命令面板（F1）运行首选项：打开远程设置命令或通过在设置编辑器中选择远程选项卡来设置 WSL 特定设置。当你打开 WSL 中的文件夹时，这些设置将覆盖你现有的任何本地设置。

高级：环境设置脚本

当 VS Code Remote 在 WSL 中启动时，不会运行 shell 启动脚本。这样做是为了避免与针对 shell 调整的启动脚本相关的问题。如果你想运行其他命令或修改环境，可以在设置脚本 ~/.vscode-server/server-env-setup（内部版：~/.vscode-server-insiders/server-env-setup）中完成。如果存在，脚本将在服务器启动之前处理。

该脚本必须是有效的 Bourne shell 脚本。请注意，无效脚本将阻止服务器启动。如果你最终得到一个阻止服务器启动的脚本，你将不得不使用常规 WSL shell 并删除或重命名设置脚本。

检查 WSL 日志（WSL：显示日志）以获取输出和错误。

高级：在容器中打开 WSL 2 文件夹

如果你正在使用 WSL 2 和 Docker Desktop 的 WSL 2 后端，你可以使用 开发容器 扩展来处理存储在 WSL 中的源代码！只需遵循以下步骤

  1. 如果你尚未安装，请安装并设置 Docker Desktop 的 WSL 2 支持。

    提示：转到设置 > 资源 > WSL 集成并启用 Docker 与你将要使用的 WSL 发行版的集成。

  2. 如果你尚未安装，请安装 开发容器 扩展以及 WSL 扩展。

  3. 接下来，像往常一样在 WSL 中打开你的源代码文件夹。

  4. 一旦你的文件夹在 WSL 中打开，从命令面板（F1）中选择开发容器：在容器中重新打开。

  5. 如果文件夹中没有 .devcontainer/devcontainer.json 文件，系统会要求你从可筛选的列表或现有 Dockerfile 或 Docker Compose 文件（如果存在）中选择一个起点。

    Select a node dev container definition

  6. VS Code 窗口（实例）将重新加载并开始构建开发容器。进度通知提供状态更新。

    Dev Container Progress Notification

  7. 构建完成后，VS Code 将自动连接到容器。你现在可以从容器内部处理你的源代码。

有关更多信息，请参阅开发容器文档。

已知限制

本节包含 WSL 常见已知问题列表。目的不是提供问题的完整列表，而是突出显示 WSL 遇到的一些常见问题。

有关 WSL 相关活动问题列表，请参阅此处。

我在 WSL 1 中尝试重命名开放工作区中的文件夹时看到 EACCES: 权限被拒绝错误

这是 WSL 文件系统实现的一个已知问题（Microsoft/WSL#3395，Microsoft/WSL#1956），由 VSCode 中活动的文件观察器引起。该问题只会在 WSL 2 中修复。

为避免此问题，请将 remote.WSL.fileWatcher.polling 设置为 true。但是，基于轮询的文件观察会影响大型工作区的性能。

对于大型工作区，您需要增加轮询间隔：remote.WSL.fileWatcher.pollingInterval 并控制被观察的文件夹：files.watcherExclude。

WSL 2 没有该文件观察器问题，也不受新设置的影响。

WSL 1 中的 Golang

问题 现有问题
Delve 调试器在 WSL 下无法工作 go-delve/delve#810, Microsoft/vscode-go#926

WSL 1 中的 Node.js

问题 现有问题
NodeJS 错误：spawn EACCES（此错误的不同变体） Microsoft/WSL#3886
Webpack HMR 无法工作 Microsoft/WSL#2709
通过 Node 使用 Firebase 仅在 WSL 上慢得无法使用 Microsoft/WSL#2657

Git 限制

如果你使用 SSH 克隆 Git 存储库并且你的 SSH 密钥有密码短语，当远程运行时，VS Code 的拉取和同步功能可能会挂起。请使用不带密码短语的 SSH 密钥，使用 HTTPS 克隆，或从命令行运行 git push 来解决此问题。

容器工具扩展限制

虽然容器工具扩展可以在远程和本地运行，但如果它已在本地安装，则在远程 SSH 主机上安装之前，你将无法在远程 SSH 主机上安装它。我们将在未来的 VS Code 版本中解决此问题。

扩展限制

许多扩展无需修改即可在 WSL 中工作。但是，在某些情况下，某些功能可能需要更改。如果你遇到扩展问题，请参阅此处总结的常见问题和解决方案，你可以在报告问题时向扩展作者提及这些问题。

此外，某些在 WSL 中使用基于 Alpine Linux 的发行版安装的扩展可能由于扩展内部本机代码中的 glibc 依赖项而无法工作。有关详细信息，请参阅使用 Linux 进行远程开发文章。

常见问题

为什么我被要求更改默认发行版？

当使用WSL：使用发行版连接到 WSL并在早于 Windows 10、2019 年 5 月更新（版本 1903）的 WSL 上运行时，你将被要求切换默认发行版，因为 WSL 命令只能在默认发行版上工作，因为它尚不支持 -d 选项。

你始终可以使用 wslconfig.exe 手动切换默认发行版。

例如

wslconfig /setdefault Ubuntu

你可以使用以下命令查看你已安装的发行版

wslconfig /l

我看到一个关于缺少库或依赖项的错误

某些扩展依赖于某些 WSL Linux 发行版的原始安装中找不到的库。你可以使用其包管理器向你的 Linux 发行版添加额外的库。对于基于 Ubuntu 和 Debian 的发行版，运行 sudo apt-get install <package> 来安装所需的库。检查你的扩展或提及的运行时的文档以获取其他安装详细信息。

WSL 扩展的连接要求是什么？

WSL 扩展和 VS Code Server 需要出站 HTTPS（端口 443）连接到

  • update.code.visualstudio.com
  • vscode.download.prss.microsoft.com
  • marketplace.visualstudio.com
  • *.gallerycdn.vsassets.io（Azure CDN）

某些扩展（如 C#）从 download.microsoft.com 或 download.visualstudio.microsoft.com 下载次要依赖项。其他扩展（如 Visual Studio Live Share）可能具有额外的连接要求。如果遇到问题，请查阅扩展的文档以获取详细信息。

服务器和 VS Code 客户端之间的所有其他通信都通过随机本地 TCP 端口完成。你可以在网络连接文章中找到 VS Code 本身需要访问的位置列表。

我身处代理之后，并且遇到连接问题

Windows 端或 WSL 端可能缺少代理设置。

当远程窗口从 VSCode 打开时，WSL 扩展会尝试在 Windows 端下载 VSCode 服务器。因此，它使用 Windows 端代理配置

当远程 VSCode 从 WSL 终端启动时，下载是使用 WSL 发行版中的 wget 完成的。代理设置可以在以下位置配置：

一旦服务器启动并运行，将使用远程选项卡上的代理设置。

我可以强制扩展在本地/远程运行吗？

扩展通常设计和测试为仅在本地或远程运行，而不是两者都运行。但是，如果扩展支持，你可以在 settings.json 文件中强制它在特定位置运行。

例如，以下设置将强制 Container Tools 扩展在本地运行，以及 Remote - SSH: Editing Configuration Files 扩展在远程运行，而不是它们的默认设置

"remote.extensionKind": {
    "ms-azuretools.vscode-containers": [ "ui" ],
    "ms-vscode-remote.remote-ssh-edit": [ "workspace" ]
}

值为 "ui" 而不是 "workspace" 将强制扩展在本地 UI/客户端侧运行。通常，这仅应在未在扩展文档中另行说明的情况下用于测试，因为它可能会破坏扩展。有关详细信息，请参阅关于支持远程开发的文章。

作为扩展作者，我需要做什么？

VS Code 扩展 API 抽象了本地/远程细节，因此大多数扩展无需修改即可工作。然而，鉴于扩展可以使用任何它们想要的 Node 模块或运行时，在某些情况下可能需要进行调整。我们建议您测试您的扩展以确保不需要更新。有关详细信息，请参阅支持远程开发。

问题或反馈

08/07/2025