在 WSL 中开发

Name: Visual Studio Code
Author: Microsoft

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

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

WSL Architecture

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

入门

注意：阅读完本主题后，您可以开始阅读入门级的 WSL 教程。

安装

要开始使用，您需要

安装 Windows Linux 子系统以及您偏好的 Linux 发行版。

注意：对于某些类型的开发，WSL 1 确实存在一些已知限制。此外，安装在 Alpine Linux 中的扩展可能因为扩展内部原生代码的 glibc 依赖而无法工作。有关详细信息，请参阅远程开发与 Linux 文章。
在 Windows 端（而非 WSL 中）安装 Visual Studio Code。

注意：在安装过程中，当系统提示选择附加任务时，请务必勾选添加到 PATH 选项，这样您就可以使用 code 命令轻松地在 WSL 中打开文件夹。
安装 WSL 扩展。如果您计划在 VS Code 中使用其他远程扩展，您可以选择安装远程开发扩展包 (Remote Development extension pack)。

打开远程文件夹或工作区

从 WSL 终端

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

打开一个 WSL 终端窗口（使用开始菜单项，或者在命令提示符/PowerShell 中输入 wsl）。
导航到您想在 VS Code 中打开的文件夹（包括但不限于 Windows 文件系统挂载点，如 /mnt/c）。
在终端中输入 code .。首次执行此操作时，您应该会看到 VS Code 正在获取在 WSL 中运行所需的组件。这只需要很短的时间，而且只需要执行一次。

注意：如果该命令不起作用，您可能需要重启终端，或者在安装时未将 VS Code 添加到 PATH 中。
片刻之后，一个新的 VS Code 窗口将会出现，您会看到一条通知，显示 VS Code 正在 WSL 中打开该文件夹。

VS Code 现在将继续在 WSL 中进行自我配置，并随着进度更新状态。
完成后，您现在可以在左下角看到一个 WSL 指示器，您可以像平常一样使用 VS Code 了！

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

从 VS Code

或者，您也可以直接从 VS Code 打开一个 WSL 窗口

启动 VS Code。
按 F1，选择 WSL: Connect to WSL（连接到默认发行版）或 WSL: Connect to WSL using Distro（连接到指定发行版）。
使用“文件”菜单打开您的文件夹。

如果您已经打开了一个文件夹，也可以使用 WSL: Reopen Folder in WSL 命令。系统会提示您选择要使用的发行版。

如果您处于 WSL 窗口中并希望在本地窗口中打开当前输入，请使用 WSL: Reopen in Windows。

从 Windows 命令提示符

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

code --remote wsl+<distro name> <path in 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

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

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

Disabled Extensions w/Install Button

您还可以通过转到“扩展”视图并使用 本地 - 已安装 标题栏右侧的云按钮选择 Install Local Extensions in WSL: {Name}，将所有本地安装的扩展安装到 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）中的 Preferences: Open Remote Settings 命令，或在设置编辑器中选择 Remote 选项卡，来设置 WSL 特定设置。只要您在 WSL 中打开文件夹，这些设置就会覆盖您现有的任何本地设置。

高级：环境设置脚本

当 VS Code Remote 在 WSL 中启动时，不会运行 shell 启动脚本。这样做是为了避免与针对 shell 优化的启动脚本出现冲突。如果您想运行其他命令或修改环境，可以在设置脚本 ~/.vscode-server/server-env-setup（Insiders 版本为：~/.vscode-server-insiders/server-env-setup）中进行。如果该脚本存在，它将在服务器启动前被处理。

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

查看 WSL 日志（WSL: Show Log）以获取输出和错误信息。

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

如果您正在使用 WSL 2 和 Docker Desktop 的 WSL 2 后端，您可以使用 Dev Containers 扩展来处理存储在 WSL 内部的源代码！只需按照以下步骤操作：

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

提示：转到 设置 > 资源 > WSL 集成 并启用与您将使用的 WSL 发行版的 Docker 集成。
如果尚未安装，请安装 Dev Containers 扩展以及 WSL 扩展。
接下来，按照平常的操作在 WSL 中打开您的源代码文件夹。
在 WSL 中打开文件夹后，从命令面板（F1）中选择 Dev Containers: Reopen in Container。
如果文件夹中没有 .devcontainer/devcontainer.json 文件，系统会要求您从可过滤列表中选择一个起点，或者使用现有的 Dockerfile 或 Docker Compose 文件（如果存在）。
VS Code 窗口（实例）将重新加载并开始构建开发容器。进度通知将提供状态更新。
构建完成后，VS Code 将自动连接到容器。现在您可以从容器内部处理您的源代码了。

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

已知限制

本节列出了 WSL 的常见问题。其目的不是提供完整的列表，而是强调在使用 WSL 时观察到的一些常见问题。

单击此处查看与 WSL 相关的活跃问题列表。

我在 WSL 1 中尝试重命名打开的工作区中的文件夹时看到 EACCES: permission denied 错误

这是 WSL 文件系统实现中的一个已知问题（Microsoft/WSL#3395, Microsoft/WSL#1956），由 VS Code 激活的文件监视器引起。该问题只会在 WSL 2 中修复。

要避免此问题，请将 remote.WSL.fileWatcher.polling 设置为 true。然而，基于轮询的文件监视会对大型工作区产生性能影响。

对于大型工作区，您需要增加轮询间隔：remote.WSL.fileWatcher.pollingInterval 并控制监视的文件夹： files.watcherExclude 在 VS Code 中打开在 VS Code Insiders 中打开。

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 来解决此问题。

容器工具扩展限制

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

扩展限制

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

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

常见问题

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

当使用 WSL: Connect to WSL using Distro 并且在早于 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 端可能缺少代理设置。

当从 VS Code 打开远程窗口时，WSL 扩展尝试在 Windows 端下载 VS Code Server。因此，它使用 Windows 端的代理配置

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

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

wget 代理设置：https://stackoverflow.com/questions/11211705/how-to-set-proxy-for-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 抽象了本地/远程细节，因此大多数扩展无需修改即可工作。但是，考虑到扩展可以使用它们想要的任何节点模块或运行时，有时可能需要进行调整。我们建议你测试你的扩展，以确保不需要更新。有关详细信息，请参阅支持远程开发。

问题或反馈

请参阅提示与技巧或常见问题解答。
在 Stack Overflow 上搜索。
添加功能请求或报告问题。
为我们的文档或VS Code 本身做出贡献。
请参阅我们的贡献指南了解详细信息。

5/28/2026