在WSL中开发

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

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

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

入门指南

注意：在查看完此主题后，您可以开始使用入门WSL教程。

安装

要开始，您需要：

1. 安装Windows 子系统 for Linux以及您喜欢的 Linux 发行版。

   注意： WSL 1 确实存在一些已知的限制，这可能会影响某些类型的开发。此外，安装在 Alpine Linux 中的扩展可能由于glibc 扩展中本地源代码的依赖项。请参阅 远程开发和 Linux 文章了解详细信息。

2. 安装 Visual Studio Code 在 Windows 侧（不在WSL中）。

   注意： 在安装过程中系统提示选择附加任务时，请确保勾选添加到 PATH选项，以便您可以轻松地在 WSL 中打开文件夹代码命令。

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

打开远程文件夹或工作区

从WSL终端

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

1. 打开一个WSL 终端Windows（使用开始菜单项或输入适用于 Linux 的 Windows 子系统从命令提示符 / PowerShell）。

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

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

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

4. 稍后，将出现一个新的 VS Code Windows，并且您会看到一个通知，说明 VS Code 正在打开 WSL 中的文件夹。

   

   VS Code 现在将继续在 WSL 中配置自己，并在进度更新时保持您最新。

5. 一旦完成，您现在会在左下角看到一个WSL指示器，您可以像平常一样使用VS Code！

   

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

来自 VS Code

或者，您可以直接从 VS Code 打开 WSL Windows：

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

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

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

从Windows命令提示符

要直接从 Windows 提示符打开 WSL Windows，请使用--远程命令行参数:

代码 --远程 wsl+<发行版名称>

例如：代码 --远程 wsl+Ubuntu /home/jim/projects/c

我们需要对输入路径是文件还是文件夹进行一些猜测。如果它有文件扩展名，则认为是文件。

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

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

为了强制打开文件，请添加--跳转或者使用：

代码 -- 文件路径 vscode-remote://wsl+Ubuntu/home/ubuntu/fileWithoutExtension

使用Git

如果你在WSL和Windows中使用相同的代码库，请确保设置一致的行尾符。请参阅提示和技巧了解详情。

您可以通过配置WSL使用Windows Git凭证管理器来避免使用密码。详情请参阅提示和技巧。

管理扩展

VS Code 在两个地方之一运行扩展：本地在UI/客户端，或在WSL中。 影响VS Code UI的扩展，如主题和片段，安装在本地，大多数扩展将位于WSL中。

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

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

需要在远程运行的本地扩展将在 本地 - 已安装 分类中显示为变暗和禁用。选择 安装 来在您的远程主机上安装扩展。

你也可以通过进入扩展视图并选择在WSL中安装本地扩展: {Name}，使用本地 - 已安装标题栏右侧的云按钮来安装所有在WSL中本地安装的扩展。这将显示一个下拉菜单，你可以从中选择在你的WSL实例中安装哪些本地安装的扩展。

在WSL中打开终端

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

您还可以使用代码从同一个终端Windows使用命令行执行一些操作，例如在WSL中打开一个新的文件或文件夹。输入代码 --help查看从命令行中有哪些可用选项。

在WSL中调试

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

请参阅调试文档，了解在中配置 VS Code 调试功能的详细信息.vscode/launch.json输入：.

WSL特定设置

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

高级：环境设置脚本

当在WSL中启动VS Code Remote时，不会运行任何 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集成 并启用您将使用的WSL发行版与Docker的集成。

2. 如果你还没有安装Dev Containers扩展和WSL扩展。

3. 接下来，在WSL中打开你的源代码文件夹，就像你通常所做的那样。

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

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

   

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

   

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

请参阅Dev Containers 文档了解更多信息。

已知限制

本节包含了一些关于WSL的常见已知问题。其目的是不是提供一个完整的问题列表，而是突出显示一些在WSL中常见的问题。

请参阅此处了解与WSL相关的活跃问题列表。

我看到 EACCES: 权限被拒绝错误，尝试在 WSL 1 的打开的代码空间中重命名一个文件夹。

这是WSL文件系统实现中的一个已知问题 (Microsoft/WSL#3395, Microsoft/WSL#1956)，由VSCode激活的文件监视器引起。该问题仅在WSL 2中修复。

为了避免该问题，请设置远程.WSL.文件监视器.轮询然而，基于轮询的文件监视对大型工作区有性能影响。

对于大型工作区，您希望增加轮询间隔：远程.WSL.文件监视器.轮询间隔并控制被监视的文件夹：

WSL 2 不会有那个文件监视器问题，并且也不会受到新设置的影响。

WSL 1 中的 Golang

Node.js 在 WSL 1

Git 限制

如果你通过 SSH 克隆一个 Git 仓库，并且你的 SSH 密钥有密码，VS Code 的拉取和同步功能在远程运行时可能会卡住。可以使用没有密码的 SSH 密钥，或者使用 HTTPS 克隆，或者运行git 推送从命令行解决此问题。

容器工具扩展限制

虽然 Container Tools 扩展可以远程和本地运行，但如果已经本地安装，您将无法在没有首先在本地卸载的情况下安装到远程 SSH 主机上。我们将在未来的 VS Code 版本中解决此问题。

扩展限制

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

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

常见问题

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

当使用WSL：使用Distro连接到WSL，并在比Windows 10 May 2019 Update（版本1903）更早的WSL上运行时，您将被要求切换默认发行版，因为WSL命令只能在默认发行版上工作，因为它不支持输入：-d选项尚未提供。

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

例如：

wslconfig /setdefault Ubuntu

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

wslconfig /l

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

某些扩展依赖于某些WSL Linux发行版的原生安装中找不到的库。您可以通过使用其包管理器将额外的库添加到您的Linux发行版中。对于基于Ubuntu和Debian的发行版，运行请将以下文本翻译成中文: sudo apt-get install 安装所需的库。查看扩展或运行时的文档以获取更多安装细节。

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

WSL 扩展和 VS Code Server 需要到以下地址的 outbound HTTPS (端口 443) 连接：

• 更新.code.visualstudio.com
• vscode下载.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 中打开一个远程Windows时，WSL 扩展会尝试在 Windows 侧下载 VSCode 服务器。因此，它使用 Windows 侧的代理配置：

• 继承自操作系统设置
• 如 Visual Studio Code 中的网络连接中所述

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

• wget代理设置：https://stackoverflow.com/questions/11211705/how-to-set-proxy-for-wget
• 手动在服务器设置脚本

一旦服务器启动并运行，远程标签页上的代理设置将被使用。

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

扩展程序通常被设计和测试为要么本地运行，要么远程运行，但不能两者都支持。然而，如果扩展程序支持，你可以强制它在你指定的某个位置运行。settings.json文件。

例如，下面的设置将强制Container Tools扩展在本地运行Remote - SSH: 编辑配置文件扩展远程运行，而不是它们的默认值：

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

一个值"ui"而不是"工作区" 将强制在本地UI/客户端上运行扩展。通常，除非扩展文档中另有说明，否则仅应在此情况下使用，因为它 可能会破坏扩展。有关详细信息，请参阅 支持远程开发 文章。

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

VS Code 扩展 API 抽象掉了本地/远程的细节，因此大多数扩展在不修改的情况下应该可以正常工作。然而，由于扩展可以使用任何他们想要的 node 模块或运行时，存在需要进行调整的情况。我们建议您测试您的扩展，以确保不需要更新。请参阅支持远程开发了解详细信息。

问题或反馈

• 查看小贴士和技巧或常见问题。
• 搜索 Stack Overflow。
• 添加一个功能请求或报告一个问题。
• 贡献到 我们的文档 或 VS Code 本身.
• 请参阅我们的贡献指南了解详情。