VSCode怎么连接WSL写python代码

江屿
江屿
发布时间:2026-11-19| 3人浏览过
原创

详细讲解在Windows系统中通过VSCode连接WSL(Windows Subsystem for Linux)编写Python代码的完整操作过程,涵盖环境准备、远程插件安装、虚拟环境配置、跨系统文件存放辨析与常见故障排查。

在 Windows 系统中编写 Python 代码时,许多与 Linux 强绑定的三方库、C 扩展或系统调用在 Windows 原生环境下容易遇到兼容性阻碍。通过 VSCode 连接 WSL(Windows Subsystem for Linux),可以让编辑器前端运行在 Windows 上享受流畅的桌面交互,而后端守护进程、Python 解释器与虚拟环境则完全运行在 WSL 的原生 Linux 系统中。本文将按照实际操作顺序,详细讲解从环境检查、扩展安装、连接进入、Python 解释器配置到代码运行与避坑排查的完整流程。
VSCode怎么连接WSL写python代码
图 1:VSCode 与 WSL2 协同开发 Python 架构概览

一、连接背后的工作机制

在开始动手之前,先理解 VSCode 是如何与 WSL 协同工作的,这有助于避免后续在安装插件或配置解释器时产生混淆。VSCode 连接 WSL 并不是单纯地通过 Windows 打开子系统的文件,而是采用了经典的客户端与服务端分离架构(Client-Server Architecture)。

当你点击连接 WSL 时,VSCode 会在 WSL 内部自动下载并启动一个无界面的守护程序 VSCode Server。在这个架构中:

  • Windows 端(Client):负责窗口渲染、输入响应、主题配色、快捷键以及通知展示,保持桌面应用级别的低延迟与流畅度。
  • WSL 端(Server):运行在 Linux 子系统内部,负责代码文件的磁盘读写、Git 状态变更、Pylance 语法静态分析、Python 调试适配器以及集成终端的实际进程。

两端通过本地进程间通信(IPC 通道)进行双向数据交换。因此,Python 相关的扩展(如 Python 语法支持、Black 格式化工具等)必须运行在 WSL 服务端,直接调用 Linux 里的 Python 解释器;而与代码运行无关的界面外观主题则保留在 Windows 本地。

VSCode怎么连接WSL写python代码
图 2:VSCode 与 WSL2 客户端-服务端分工与协议交互机制

二、操作前的准备工作与环境检查

顺利连接的前提是 Windows 端已具备完备的 WSL2 实例与 VSCode 宿主程序。请按照以下步骤检查环境基础。

1. 检查 WSL 实例状态

在 Windows 中打开 PowerShell 终端,执行以下命令确认子系统版本:

PowerShell 命令
wsl -l -v
示例输出:
  NAME      STATE           VERSION
* Ubuntu    Running         2
提示:确保发行版的 VERSION 为 2。WSL2 拥有完整的 Linux 内核与独立的虚拟化磁盘镜像(ext4.vhdx),而老旧的 WSL1 存在系统调用兼容性不足和 I/O 监控受限的问题。如果显示为 1,可执行 wsl --set-version Ubuntu 2 进行升级。

2. 在 Windows 端安装 WSL 扩展

在 Windows 系统中启动 VSCode,点击左侧边栏的扩展图标(或按快捷键 Ctrl + Shift + X),在搜索框中输入 WSL。

找到由 Microsoft 官方发布的 WSL 扩展(扩展唯一标识符为 ms-vscode-remote.remote-wsl),点击“安装(Install)”。安装完成后,VSCode 界面左下角会出现一个带有左右箭头符号的状态图标(><)。

3. 在 WSL 内部安装 Python 与虚拟环境工具

启动 Ubuntu 终端(可通过开始菜单启动,或在 PowerShell 中输入 wsl)。很多基础 Linux 镜像自带了 Python,但通常缺少 pip 和用于创建虚拟环境的 venv 模块。在终端中执行以下命令补齐依赖:

WSL Bash 命令
sudo apt update && sudo apt install -y python3 python3-pip python3-venv
验证命令与示例输出:
python3 --version
# 示例输出:Python 3.10.12(或当前系统对应版本)

三、连接 WSL 并配置 Python 环境的具体步骤

完成基础准备后,即可正式建立连接并初始化 Python 项目。以下六个步骤展示了标准的操作全流程:

VSCode怎么连接WSL写python代码
图 3:连接 WSL 并配置 Python 运行环境的完整步骤

步骤 1:在 WSL 原生目录下建立工程文件夹

在 WSL 终端中,切换至你的 Linux 用户家目录(~),创建用于存放代码的目录并进入:

WSL Bash 命令
mkdir -p ~/projects/py-demo
cd ~/projects/py-demo

步骤 2:通过终端唤起 VSCode

在当前目录的 WSL 终端中,直接输入以下命令:

WSL Bash 命令
code .

如果是首次在 WSL 目录下调用 code .,终端会自动输出下载并解压 VSCode Server 的过程:

首次连接时的示例输出:
Updating VS Code Server to version xxx...
Installing VS Code Server for x64 (xxx)...
Downloading: 100%
Unpacking: 100%
Server did subvert to daemon!
Done !!

随后,Windows 桌面会自动弹出一个崭新的 VSCode 窗口。观察窗口左下角状态栏,原先的箭头图标现在明确显示为 WSL: Ubuntu。这表明当前窗口已挂载并运行在 WSL 子系统语境下。

备用唤起方式:如果你没有打开 WSL 终端,也可以在 Windows 中直接打开 VSCode,点击左下角的远程图标(或按 Ctrl + Shift + P 输入并选择 WSL: Connect to WSL),连接成功后再通过顶部菜单 文件 -> 打开文件夹,输入 /home/你的用户名/projects/py-demo。

步骤 3:在 WSL 端安装 Python 官方扩展

尽管你在 Windows 本地可能已经安装过 Python 扩展,但在 WSL 远程窗口中,Python 语言支持必须单独部署到远程 Linux 服务端:

  1. 在已连接 WSL 的 VSCode 窗口中,按快捷键 Ctrl + Shift + X 打开扩展视图。
  2. 搜索 Python(由 Microsoft 出品)。
  3. 此时按钮会明确提示为 “在 WSL: Ubuntu 中安装(Install in WSL: Ubuntu)”,点击安装。安装完毕后,该扩展会被归类在 WSL: UBUNTU - 已安装 分组下。

步骤 4:创建 Python 虚拟环境(Virtual Environment)

在 Python 开发中,始终推荐为每一个独立项目创建专用虚拟环境,避免污染 Linux 系统自带的 Python 全局库。在 VSCode 菜单栏中点击 终端 -> 新建终端(快捷键 Ctrl + `)。

注意观察终端标签,它直接打开的是 WSL 的 Bash 终端,命令提示符为 user@hostname:~/projects/py-demo$。在终端中执行:

VSCode 内置终端命令
python3 -m venv .venv

执行完成后,左侧文件资源管理器中会出现一个名为 .venv 的目录结构,里面包含独立的 Python 可执行文件与 site-packages 目录。

步骤 5:选定 Python 解释器

为了让 VSCode 的代码提示、跳转与运行绑定刚刚创建的虚拟环境:

  1. 按快捷键 Ctrl + Shift + P 打开命令面板。
  2. 输入并选择 Python: Select Interpreter(选择解释器)。
  3. VSCode 会自动扫描当前项目目录,并在列表中列出推荐选项:Python 3.x.x ('.venv': venv) ./.venv/bin/python。
  4. 点击选中该项。选中后,VSCode 窗口右下角(或状态栏)会显示当前激活的解释器路径为 ('.venv': venv)。

步骤 6:编写测试脚本与断点调试

在文件树中新建文件 main.py,输入以下测试代码,验证当前代码所处的操作系统环境与三方库安装能力:

main.py 代码示例
import platform
import sys

def verify_environment():
    system_name = platform.system()
    python_path = sys.executable
    print(f"当前执行操作系统: {system_name}")
    print(f"当前解释器路径: {python_path}")
    
    if system_name.lower() == "linux" and ".venv" in python_path:
        print("环境检测正常:代码完全运行在 WSL Linux 虚拟环境中。")
    else:
        print("环境异常:未正确指向 WSL 虚拟环境。")

if __name__ == "__main__":
    verify_environment()

运行与验证方式:

  • 终端直接运行:在内置终端中执行 source .venv/bin/activate && python main.py。
  • 一键调试运行:在 main.py 编辑窗口中,在代码第 9 行左侧点击留下一个红点(断点),随后按 F5 键,选择“Python 文件(调试当前活动文件)”。程序将精确暂停在断点处,你可以直接在左侧查看变量值、单步执行,调试过程完全由 WSL 内部的 debugpy 驱动。
终端运行示例输出:
当前执行操作系统: Linux
当前解释器路径: /home/username/projects/py-demo/.venv/bin/python
环境检测正常:代码完全运行在 WSL Linux 虚拟环境中。

四、容易混淆的关键做法与深度辨析

初次在 Windows 与 WSL 混合环境下写代码时,常有一些看似便利的直觉做法,但在实际项目中却会引发性能瓶颈或环境故障。

VSCode怎么连接WSL写python代码
图 4:WSL 原生 ext4 存储与跨挂载盘(/mnt/c)的架构与性能差异

辨析一:为什么不建议把代码放在 Windows 盘(如 D 盘通过 /mnt/d 访问)?

常见做法:很多人习惯在 Windows 的 D:\workspace\project 建立文件夹,然后在 WSL 终端中 cd /mnt/d/workspace/project 去运行代码。这种想法很自然:代码在 Windows 盘里,随时可以用 Windows 其他软件直接查看。

深层原因与问题:WSL2 是一个基于轻量级虚拟机的架构。WSL2 访问 /mnt/c 或 /mnt/d 时,必须通过网络协议(9P 协议)跨越虚拟机边界去访问 Windows 的 NTFS 文件系统。

  • I/O 速度骤降:Python 项目包含大量的依赖包。当你执行 pip install pandas 或 npm install 时,会在几秒内产生成千上万个小文件。在 /mnt/ 路径下,文件创建与读写速度往往比原生 ext4 慢 5 到 10 倍,导致安装依赖极度缓慢。
  • 文件监听(inotify)失效:在使用 FastAPI、Flask 或 Django 时,开发服务器依赖 Linux 内核的 inotify 机制实现“代码修改后自动热重载”。跨越 9P 协议时,Windows 侧的文件变动事件经常无法完整传递给 Linux,导致代码改动后服务不自动刷新。

正确规范:始终将项目存放在 WSL 的 Linux 原生分区(即 /home/username/)。如果你需要用 Windows 文件管理器查看代码,直接在 Windows 资源管理器地址栏输入 \\wsl$\Ubuntu\home\username,或者在 WSL 终端中输入 explorer.exe . 即可直接打开对应的 Linux 目录。

辨析二:Windows 端装了 Python 扩展,WSL 里为什么还要再装一遍?

容易产生的误解:用户认为 VSCode 插件只要在本地安装了一次,就能全局对所有项目生效。

成立条件与修正:外观类扩展(如 One Dark Pro 等主题插件)确实只需在 Windows 本地安装一次,因为主题渲染发生在客户端。但 Python 扩展、Pylance 和调试器不仅提供代码高亮,更重要的是要在后台分析 Linux 环境中的第三方库代码(分析 /usr/lib 或 .venv/lib 下的文件),并启动调试代理进程。如果这些扩展运行在 Windows 端,它们无法高效感知 Linux 子系统内的动态链接库与模块结构。因此,代码分析与调试类插件必须安装在远程服务节点中。

五、全流程核对与高频异常排查

完成上述配置后,可以通过下述四个指标快速核对环境是否完全就绪,并在遇到异常时快速定位根因。

VSCode怎么连接WSL写python代码
图 5:连接状态自检指标与常见异常排查决策树

1. 关键指标核对表

  • 状态栏标识:VSCode 左下角绿底(或主题底色)区域必须显示 WSL: <发行版名称>。如果显示为本地无标识,说明当前仍处于 Windows 本地编辑模式。
  • 集成终端类型:在 VSCode 内按 Ctrl + ` 打开终端,终端标题应为 bash 或 zsh,执行 uname 应输出 Linux。
  • 解释器标识:状态栏右侧或解释器选择面板中,解释器路径必须以 Linux 风格的斜杠开头(如 /home/.../.venv/bin/python),不能是类似 C:\Python310\python.exe 的 Windows 路径。

2. 常见问题与解决方法

问题一:在 WSL 终端输入 code . 提示 command not found
原因:Windows 的环境变量没有正确透传给 WSL,或者安装 VSCode 时未勾选“将 Code 添加到 PATH 环境变量”。
解决方法:
  1. 检查 WSL 中的 /etc/wsl.conf 文件,确认没有禁用互操作性配置。文件中不应存在 [interop] \n appendWindowsPath = false。
  2. 如果在 Windows 中重新安装 VSCode,请在安装向导中务必勾选“添加到 PATH(系统重启后生效)”。
  3. 作为临时方案,你可以在 Windows 端直接打开 VSCode,按 F1 搜索 WSL: Connect to WSL 连接进入。
问题二:明明 pip 安装了模块,编辑器却持续显示黄色波浪线“Import could not be resolved”
原因:当前 VSCode 编辑器选定的 Python 解释器与你在终端中 pip 安装时使用的环境不一致(例如在全局环境安装了包,但解释器选了未安装包的虚拟环境,反之亦然)。
解决方法:
  1. 在终端中执行 which python,查看当前正在运行的 Python 具体路径。
  2. 在 VSCode 中按 Ctrl + Shift + P,输入 Python: Select Interpreter,将选定的解释器与刚才终端输出的路径严格对齐。
  3. 若路径一致但仍有黄色波浪线,可按 Ctrl + Shift + P 运行 Developer: Reload Window 重新加载窗口索引缓存。
问题三:在 WSL 里用 Python 启动了 Web 服务(如 FastAPI / Flask),Windows 浏览器打不开
原因:监听地址限制为仅本机内部回路,或端口未完成绑定。
解决方法:
  1. 启动脚本时,将 host 参数指定为 0.0.0.0(例如 uvicorn main:app --host 0.0.0.0 --port 8000),允许子系统网卡接收外部访问。
  2. 在 VSCode 底部的“端口(Ports)”面板中,查看该端口是否已显示在端口转发列表中。WSL2 具备自动 localhost 转发机制,通常在 Windows 浏览器直接访问 http://localhost:8000 即可畅通连接。
相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。