WSL开发

Visual Studio Code WSL 扩展让你直接从 VS Code 使用 Windows Subsystem for Linux （WSL） 作为全职开发环境。你可以在基于Linux的环境中开发，使用Linux专用的工具链和工具，并运行和调试基于Linux的应用程序，所有这些都来自Windows的舒适环境。

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

WSL架构

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

入门

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

安装

要开始，你需要：

  1. 安装Windows子系统（Linux）以及你喜欢的Linux发行版。

    注：WSL 1 在某些类型的显影方面确实存在一些已知的限制。此外，Alpine Linux 中安装的扩展可能无法使用，原因包括格利比克扩展内部原生源代码中的依赖。详情请参见远程开发与Linux相关文章。

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

    注：安装过程中提示选择额外任务时，务必勾选“添加到PATH”选项，这样你就能轻松地在WSL中使用代码指挥部。

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

打开一个远程文件夹或工作区

从WSL终点站

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

  1. 打开WSL终端窗口（使用开始菜单项或输入WSL来自命令提示符 / PowerShell）。

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

  3. 类型代码。在终端里。第一次这样做时，你应该会看到 VS Code 获取在 WSL 运行所需的组件。这通常只需短时间，且只需一次。

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

  4. 过了一会儿，会出现一个新的VS Code窗口，你会看到VS Code正在WSL中打开文件夹的通知。

    WSL启动通知

    VS Code 现在将继续在 WSL 中自我配置，并在进展时及时更新。

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

    WSL状态条项

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

摘自VS Code。

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

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

如果你已经打开了文件夹，也可以在 WSL 命令中使用 WSL： Reopen Folder。系统会提示你使用哪个发行版。

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

来自Windows命令提示符

要直接从Windows提示符打开WSL窗口，请使用——远程命令行参数：

代码 --远程WSL+<发行版名称> <路径在WSL中运行>

例如：Code --remote WSL+Ubuntu /home/jim/projects/c

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

要强制打开文件夹，可以在路径上添加斜杠，或者使用：

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

要强制打开文件，添加——去或使用：

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

与 Git 合作

如果你在WSL和Windows中使用的是同一个仓库，务必设置一致的行尾。详情请参见技巧和窍门。

你也可以通过配置 WSL 使用Windows Git凭证管理器来避免密码。详情请参见技巧和窍门。

管理扩展

VS Code 在两个地方运行扩展：在本地的 UI/客户端运行，或者在 WSL 中运行。影响VS Code界面的扩展，比如主题和片段，都是本地安装的，但大多数扩展会安装在WSL内部。

如果你从扩展视图安装扩展，它会自动安装到正确的位置。安装后，你可以根据分类分组判断扩展安装的位置。将设有本地-安装类别和WSL类别。

工作区扩展类别

局部扩展类别

注：如果您是扩展作者，且扩展无法正常工作或安装在错误位置，详情请参见支持远程开发。

真正需要远程运行的本地扩展会在本地 - 已安装类别中显示为调暗并禁用。选择安装，在远程主机上安装扩展。

禁用带安装按钮的扩展

你也可以在 WSL 中安装所有本地安装的扩展，方法是进入扩展视图，使用本地 - 已安装标题栏右侧的云端按钮选择“在 WSL 安装本地扩展：{Name}。它会显示一个下拉菜单，你可以选择在你的 WSL 实例中安装哪些本地安装的扩展。

安装所有扩展

在WSL开设终端

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

你也可以使用代码在同一终端窗口中执行命令行作，如在 WSL 中打开新文件或文件夹。类型代码——帮助看看命令行有哪些选项。

使用代码CLI的应用

WSL 中的调试

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

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

WSL专属设置

VS Code 的本地用户设置在你打开 WSL 文件夹时也会被重用。虽然这样可以保持用户体验的一致性，但你可能需要在本地机器和 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集成，启用与你将要使用的WSL发行版的Docker集成。

  2. 如果你还没安装，可以同时安装 Dev Containers 扩展和 WSL 扩展。

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

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

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

    选择节点开发容器定义

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

    开发容器进度通知

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

更多信息请参见开发容器文档。

已知的局限性

本节包含WSL常见问题列表。本节旨在提供完整的问题清单，而是突出WSL常见的一些问题。

这里有与WSL相关的活跃议题列表。

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

这是WSL文件系统实现（Microsoft/WSL#3395，Microsoft/WSL#1956）中一个已知的问题，原因是VSCode激活了文件监视器。这个问题只有在WSL 2中才会修复。

为了避免这个问题，设置偏远。WSL.fileWatcher.polling真是太真实了。然而，基于轮询的文件监控对大型工作区的性能有影响。

对于大型工作区，你需要延长轮询间隔：偏远。WSL.fileWatcher.pollingInterval并控制被监控的文件夹：

files.watcherExclude
  • 在VS代码中打开
  • 在VS Code Insiders中开放
.

WSL 2 没有那个文件监视者的问题，也不受新设置影响。

WSL 1中的Golang

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

WSL 1中的Node.js

子嗣 现有问题
NodeJS 错误：生成 EACES（该错误的不同变体） Microsoft/WSL#3886
Webpack HMR 无法工作 Microsoft/WSL#2709
通过节点的Firebase只有在WSL下才慢得不可用 Microsoft/WSL#2657

Git 限制

如果你用SSH克隆了一个Git仓库，且你的SSH密钥带有密码短语，VS Code的拉取和同步功能在远程运行时可能会卡住。要么用无密码的SSH密钥，要么用HTTPS克隆，要么直接运行Git 推送从命令行开始绕过这个问题。

容器工具扩展的限制

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

扩展限制

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

此外，使用基于Alpine Linux的发行版时，WSL中安装的一些扩展可能无法正常工作，原因包括格利比克扩展内部原生代码中的依赖关系。详情请参见《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代码服务器要求通过出站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 服务器。因此，它使用窗口侧代理配置：

当远程VSCode从WSL终端启动时，下载过程是通过WGET在WSL发行版中。代理设置可以配置如下：

服务器运行后，会使用远程标签页上的代理设置。

我能强制扩展程序在本地/远程运行吗？

扩展通常设计和测试为本地运行或远程运行，而非两者兼有。不过，如果扩展支持它，你可以强制它在你的某个特定位置运行settings.json档案。

例如，下面的设置将强制容器工具扩展在本地运行，远程运行 - SSH： 编辑配置文件扩展名，而不是它们的默认扩展：

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

一个值为“ui”代替“工作空间”会强制扩展在本地UI/客户端运行。通常，除非扩展文档另有说明，否则这只应用于测试，因为这可能会破坏扩展。详情请参见“支持远程开发”一文。

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

VS Code 扩展 API 会抽象本地/远程细节，所以大多数扩展无需修改即可工作。然而，鉴于扩展可以使用任意节点模块或运行时，在某些情况下可能需要做出调整。我们建议您测试扩展，确保无需更新。详情请参见支持远程开发。

问题或反馈