现已推出！阅读 10 月份的新功能和修复。

在 WSL 中进行开发

Visual Studio Code WSL 扩展允许您直接从 VS Code 使用 Windows Subsystem for Linux (WSL) 作为您的全职开发环境。您可以使用基于 Linux 的环境进行开发，使用 Linux 特定的工具链和实用程序，并运行和调试基于 Linux 的应用程序，所有这些都在 Windows 的舒适环境中完成。

该扩展直接在 WSL 中运行命令和其他扩展，因此您可以编辑位于 WSL 或已挂载的 Windows 文件系统（例如 /mnt/c）中的文件，而无需担心路径问题、二进制兼容性或其他跨操作系统挑战。

WSL Architecture

这使得 VS Code 能够提供本地质量的开发体验——包括完整的 IntelliSense（代码补全）、代码导航和调试——无论您的代码托管在何处。

入门

注意：在查看本主题后，您可以开始使用介绍性的 WSL 教程。

安装

要开始使用，您需要

  1. 安装 Windows Subsystem for Linux 以及您首选的 Linux 发行版。

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

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

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

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

打开远程文件夹或工作区

从 WSL 终端

在 VS Code 中打开 Windows Subsystem for Linux 内的文件夹与从命令提示符或 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 后端，您可以使用Dev Containers扩展来处理存储在 WSL 中的源代码！只需按照以下步骤操作。

  1. 如果您还没有，请安装并设置 Docker Desktop 的 WSL 2 支持。

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

  2. 如果您还没有，请安装Dev Containers扩展以及 WSL 扩展。

  3. 接下来，在 WSL 中打开您的源代码文件夹，就像您平时一样。

  4. 在 WSL 中打开文件夹后，从命令面板 (F1) 中选择Dev Containers：在容器中重新打开。

  5. 如果该文件夹中没有.devcontainer/devcontainer.json文件，您将被要求从一个可过滤列表中选择一个起点，或选择一个现有的Dockerfile或Docker Compose 文件（如果存在）。

    Select a node dev container definition

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

    Dev Container Progress Notification

  7. 构建完成后，VS Code 将自动连接到容器。您现在可以在容器内使用您的源代码。

有关更多信息，请参见Dev Containers 文档。

已知限制

本节包含 WSL 常用问题的列表。其目的不是提供一个完整的错误列表，而是突出显示在 WSL 中遇到的常见问题。

有关与 WSL 相关的活动问题列表，请点击此处。

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

这是 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
Firebase 通过 node 速度非常慢，只在 WSL 上出现 Microsoft/WSL#2657

Git 限制

如果您使用 SSH 克隆 Git 仓库，并且您的 SSH 密钥有密码，那么 VS Code 的拉取和同步功能在远程运行时可能会挂起。您可以使用没有密码的 SSH 密钥，使用 HTTPS 克隆，或从命令行运行git push来解决这个问题。

Docker 扩展限制

虽然 Docker 扩展可以在远程和本地运行，但如果它已经安装在本地，您将无法在远程 SSH 主机上安装它，除非先在本地卸载它。我们将在未来的 VS Code 版本中解决这个问题。

扩展限制

许多扩展可以在 WSL 中运行，无需修改。但是，在某些情况下，某些功能可能需要更改。如果您遇到扩展问题，请点击此处查看常见问题和解决方案的摘要，您可以在报告问题时将其告知扩展作者。

此外，在使用基于 Alpine Linux 的发行版时，安装在 WSL 中的某些扩展可能无法工作，因为扩展中的原生代码中存在glibc依赖关系。有关详细信息，请参见使用 Linux 进行远程开发文章。

常见问题

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

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

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

例如

wslconfig /setdefault Ubuntu

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

wslconfig /l

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

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

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

WSL 扩展和 VS Code Server 需要与以下地址进行外向 HTTPS（端口 443）连接。

  • update.code.visualstudio.com
  • marketplace.visualstudio.com
  • vscode.blob.core.windows.net
  • *.vo.msecnd.net（Azure CDN）
  • *.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 侧的代理配置。

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

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

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

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

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

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

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

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

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

问题或反馈

10/29/2024