在 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 安装。
这使得 VS Code 能够提供本地质量的开发体验——包括完整的 IntelliSense(代码补全)、代码导航和调试——无论您的代码托管在哪里。
入门
注意:阅读本主题后,您可以开始学习入门 WSL 教程。
安装
要开始使用,您需要
-
安装 适用于 Linux 的 Windows 子系统 以及您首选的 Linux 发行版。
注意:WSL 1 在某些类型的开发方面确实存在一些已知限制。此外,由于扩展内部的本机源代码中存在
glibc
依赖项,安装在 Alpine Linux 中的扩展可能无法工作。有关详细信息,请参阅远程开发和 Linux 文章。 -
在 Windows 端(而不是 WSL 中)安装 Visual Studio Code。
注意:在安装过程中,当提示选择其他任务时,请务必勾选添加到 PATH 选项,这样您就可以使用
code
命令轻松地在 WSL 中打开文件夹。
打开远程文件夹或工作区
从 WSL 终端
在 VS Code 中打开适用于 Linux 的 Windows 子系统中的文件夹与从命令提示符或 PowerShell 中打开 Windows 文件夹非常相似。
-
打开一个 WSL 终端窗口(通过开始菜单项或在命令提示符/PowerShell 中键入
wsl
)。 -
导航到您想在 VS Code 中打开的文件夹(包括但不限于 Windows 文件系统挂载点,例如
/mnt/c
) -
在终端中键入
code .
。首次执行此操作时,您应该会看到 VS Code 正在获取在 WSL 中运行所需的组件。这只需要一小段时间,并且只需要执行一次。注意:如果此命令不起作用,您可能需要重新启动终端,或者在安装 VS Code 时可能没有将其添加到您的路径中。
-
片刻之后,一个新的 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)以使用默认发行版,或者选择 WSL: Connect to WSL using Distro(使用发行版连接到 WSL)以使用特定发行版。
- 使用“文件”菜单打开您的文件夹。
如果您已经打开了一个文件夹,您还可以使用 WSL: Reopen Folder in WSL(在 WSL 中重新打开文件夹)命令。系统将提示您选择要使用的发行版。
如果您在 WSL 窗口中并想在本地窗口中打开当前输入,请使用 WSL: Reopen in Windows(在 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 的类别。
注意:如果您是扩展作者,并且您的扩展无法正常工作或安装在错误的位置,请参阅支持远程开发了解详细信息。
实际上需要在远程运行的本地扩展将在本地 - 已安装类别中显示为灰色和禁用。选择安装以在您的远程主机上安装扩展。
您还可以通过前往“扩展”视图并使用本地 - 已安装标题栏右侧的云按钮选择 在 WSL 中安装本地扩展: {名称} 来在 WSL 中安装所有本地安装的扩展。这将显示一个下拉列表,您可以在其中选择要在 WSL 实例中安装哪些本地安装的扩展。
在 WSL 中打开终端
从 VS Code 在 WSL 中打开终端很简单。一旦在 WSL 中打开了文件夹,您在 VS Code 中打开的任何终端窗口(终端 > 新终端)都将自动在 WSL 中运行,而不是在本地运行。
您还可以从同一个终端窗口使用 code
命令行执行多项操作,例如在 WSL 中打开新文件或文件夹。键入 code --help
以查看命令行中可用的选项。
在 WSL 中调试
在 WSL 中打开文件夹后,您可以像在本地运行应用程序时一样使用 VS Code 的调试器。例如,如果您在 launch.json
中选择一个启动配置并开始调试 (F5),应用程序将在远程主机上启动并将调试器附加到它。
有关在 .vscode/launch.json
中配置 VS Code 调试功能的详细信息,请参阅调试文档。
WSL 特定设置
当您在 WSL 中打开文件夹时,VS Code 的本地用户设置也会被重用。虽然这能保持您的用户体验一致,但您可能希望在本地计算机和 WSL 之间改变一些设置。幸运的是,连接到 WSL 后,您还可以通过从命令面板 (F1) 运行 首选项:打开远程设置 命令或在“设置”编辑器中选择远程选项卡来设置 WSL 特定设置。无论何时您在 WSL 中打开文件夹,这些设置都将覆盖您现有的任何本地设置。
高级:环境设置脚本
当在 WSL 中启动 VS Code 远程时,不会运行任何 shell 启动脚本。这样做是为了避免针对 shell 调整的启动脚本引起的问题。如果您想运行其他命令或修改环境,可以在设置脚本 ~/.vscode-server/server-env-setup
(Insiders 版:~/.vscode-server-insiders/server-env-setup
)中完成。如果存在,该脚本会在服务器启动前进行处理。
该脚本需要是一个有效的 Bourne shell 脚本。请注意,无效的脚本将阻止服务器启动。如果您最终使用的脚本阻止了服务器启动,您将不得不使用常规的 WSL shell 并删除或重命名该设置脚本。
检查 WSL 日志(WSL:显示日志)以获取输出和错误信息。
高级:在容器中打开 WSL 2 文件夹
如果您正在使用 WSL 2 和 Docker Desktop 的 WSL 2 后端,您可以使用 开发容器 扩展来处理存储在 WSL 中的源代码!只需遵循以下步骤
-
如果您尚未进行,请安装并设置 Docker Desktop 的 WSL 2 支持。
提示:前往设置 > 资源 > WSL 集成并启用 Docker 与您将使用的 WSL 发行版的集成。
-
如果您尚未进行,请安装 开发容器 扩展以及 WSL 扩展。
-
接下来,像往常一样在 WSL 中打开您的源代码文件夹。
-
一旦您的文件夹在 WSL 中打开,从命令面板 (F1) 选择 开发容器: 在容器中重新打开。
-
如果文件夹中没有
.devcontainer/devcontainer.json
文件,系统将要求您从可筛选列表中或现有的 Dockerfile 或 Docker Compose 文件(如果存在)中选择一个起点。 -
VS Code 窗口(实例)将重新加载并开始构建开发容器。进度通知将提供状态更新。
-
构建完成后,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 主机上安装,除非先在本地卸载它。我们将在未来的 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 发行版的原始安装中未找到的库。您可以使用其包管理器将其他库添加到您的 Linux 发行版中。对于基于 Ubuntu 和 Debian 的发行版,运行 sudo apt-get install <package>
以安装所需的库。请查阅您的扩展或提到的运行时的文档以获取其他安装详细信息。
WSL 扩展的连接要求是什么?
WSL 扩展和 VS Code 服务器需要出站 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 端的代理配置
- 继承自操作系统设置
- 如Visual Studio Code 中的网络连接中所述
当从 WSL 终端启动远程 VSCode 时,下载是使用 WSL 发行版中的 wget
完成的。代理设置可以在以下位置配置
一旦服务器启动并运行,将使用“远程”选项卡上的代理设置。
我可以强制扩展在本地/远程运行吗?
扩展通常设计和测试为仅在本地或远程运行,而不是两者都运行。但是,如果扩展支持,你可以在 settings.json
文件中强制它在特定位置运行。
例如,以下设置将强制 容器工具 扩展在本地运行,并强制 远程 - SSH:编辑配置文件 扩展在远程运行,而不是使用它们的默认设置。
"remote.extensionKind": {
"ms-azuretools.vscode-containers": [ "ui" ],
"ms-vscode-remote.remote-ssh-edit": [ "workspace" ]
}
值 "ui"
而不是 "workspace"
将强制扩展在本地 UI/客户端运行。通常,这仅应用于测试,除非扩展的文档中另有说明,因为它可能会破坏扩展。有关详细信息,请参阅支持远程开发一文。
作为扩展作者,我需要做什么?
VS Code 扩展 API 抽象了本地/远程细节,因此大多数扩展无需修改即可工作。然而,鉴于扩展可以使用它们想要的任何节点模块或运行时,在某些情况下可能需要进行调整。我们建议您测试您的扩展以确保不需要任何更新。有关详细信息,请参阅支持远程开发。
问题或反馈
- 请参阅提示和技巧或常见问题解答。
- 在 Stack Overflow 上搜索。
- 添加功能请求或报告问题。
- 为我们的文档或VS Code 本身做出贡献。
- 请参阅我们的贡献指南了解详细信息。