在 WSL 中通过 VSCode/Cursor+Cond 虚拟环境运行 Python 代码 全教程

在 WSL 中通过 VSCode/Cursor+Cond 虚拟环境运行 Python 代码 全教程

本文基于你已安装 WSL的前提，重点讲解「WSL 中安装 Miniconda→创建 Python 虚拟环境→VSCode/Cursor 连接 WSL 并使用 conda 环境运行代码」的完整流程，步骤精准可落地。

一、核心前提

• 已启用 WSL2（Ubuntu/Debian 等发行版），且能正常启动终端；
• Windows 端已安装 VSCode/Cursor（建议最新版本）；
• 网络通畅（需下载 Miniconda 和 Python 包）。

二、步骤 1：在 WSL 中安装 Miniconda

WSL 默认无 conda 环境，需先安装轻量版 Miniconda（替代 Anaconda，节省空间）。

1. 打开 WSL 终端

• 按下Win + R，输入wsl回车，或直接打开 Ubuntu 终端；
• 确保当前为普通用户（避免全程 root 操作）。

2. 下载 Miniconda 安装包

执行以下命令下载适配 Linux（x86_64）的 Miniconda3 安装包（2024 版）：

bash

运行

# 下载Miniconda安装脚本（国内镜像加速，推荐）
wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh

# 若wget未安装，先执行：sudo apt install -y wget

3. 执行安装脚本

bash

运行

# 运行安装脚本（bash而非sh，避免兼容性问题）
bash miniconda.sh

4. 安装交互步骤（关键）

5. 验证 Miniconda 安装

• 关闭当前 WSL 终端，重新打开（让环境变量生效）；
• 执行以下命令，若输出 conda 版本号则安装成功：

  bash

  运行

  conda –version
  # 示例输出：conda 24.5.0

• 首次启动终端会显示(base)前缀，说明默认激活了 base 环境（后续可关闭，见下方优化）。

6. （可选）优化 conda 默认行为

默认每次打开终端都会激活 base 环境，可关闭：

bash

运行

conda config –set auto_activate_base false

关闭后，重新打开终端，(base)前缀消失，需手动激活环境。

三、步骤 2：在 WSL 中创建 conda Python 虚拟环境

1. （可选）配置 conda 国内镜像（加速下载）

避免下载 Python 包时速度慢，配置清华镜像：

bash

运行

# 创建conda配置文件
mkdir -p ~/.condarc
# 写入镜像配置（覆盖原有内容）
cat > ~/.condarc << EOF
channels:
– defaults
show_channel_urls: true
default_channels:
– https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
– https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
– https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2
custom_channels:
conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
msys2: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
bioconda: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
menpo: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
pytorch-lts: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
simpleitk: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
EOF
# 清除缓存
conda clean -i

2. 创建 conda 虚拟环境

bash

运行

# 创建名为python_wsl_env的环境，指定Python版本（推荐3.10/3.11）
conda create -n python_wsl_env python=3.10 -y
# 参数说明：
# -n：环境名称（自定义，如py310、my_project）
# python=3.10：指定Python版本
# -y：自动确认所有安装选项，无需手动输入yes

3. 管理 conda 虚拟环境（常用命令）

4. 验证虚拟环境

激活环境后，执行以下命令，确认 Python 路径指向 conda 环境：

bash

运行

conda activate python_wsl_env
# 查看Python路径
which python
# 示例输出：/home/你的用户名/miniconda3/envs/python_wsl_env/bin/python
# 查看Python版本
python –version
# 示例输出：Python 3.10.14

四、方案 1：VSCode 连接 WSL+conda 环境运行 Python

1. 安装 VSCode 必备插件

打开 Windows 端 VSCode，在左侧「扩展商店」（Ctrl+Shift+X）安装：

• Remote – WSL（微软官方）：核心插件，用于连接 WSL；
• Python（微软官方）：支持 conda 环境识别、代码运行 / 调试；
• Pylance（自动随 Python 插件安装）：增强 Python 语法提示。

2. 连接 VSCode 到 WSL

方式 1：命令面板连接

• 按下Ctrl+Shift+P打开命令面板；
• 输入「WSL: Connect to WSL」，选择你的 WSL 发行版（如 Ubuntu-22.04）；
• 等待连接完成，VSCode 左下角会显示「WSL: Ubuntu-22.04」，表示已进入 WSL 环境。

方式 2：WSL 终端启动 VSCode

• 打开 WSL 终端，激活 conda 环境（可选），进入项目目录：

  bash

  运行

  cd ~ # 进入用户主目录，或自定义项目目录如mkdir -p ~/python_project && cd ~/python_project
  code . # 在当前目录启动VSCode（自动连接WSL）

3. 打开 WSL 项目目录

• 点击 VSCode 左侧「资源管理器」（Ctrl+Shift+E）→「打开文件夹」；
• 选择 WSL 中的目录（如~/python_project），点击「确定」；
• 若提示「信任此文件夹」，选择「是」（否则无法正常运行代码）。

4. 选择 conda 虚拟环境作为解释器

• 按下Ctrl+Shift+P，输入「Python: Select Interpreter」；
• 在弹出的列表中，找到并选择你的 conda 环境：✅ 正确路径示例：~/miniconda3/envs/python_wsl_env/bin/python❌ 避免选系统 Python（/usr/bin/python3）或 base 环境；
• 选择后，VSCode 右下角会显示「Python 3.10.14 ('python_wsl_env': conda)」，表示配置成功。

5. 运行 / 调试 Python 代码

步骤 1：新建测试文件

在 VSCode 中右键项目目录→「新建文件」，命名为test_conda.py，输入代码：

python

运行

import sys
import numpy # 若已安装numpy，可验证包是否可用

print("Python解释器路径：", sys.executable)
print("Python版本：", sys.version)
print("numpy版本：", numpy.__version__) # 未安装则注释此行
print("Hello from WSL conda env!")

步骤 2：运行代码（3 种方式）

五、方案 2：Cursor 连接 WSL+conda 环境运行 Python

Cursor 基于 VSCode 内核，配置逻辑与 VSCode 一致，仅界面略有差异，核心步骤如下：

1. 安装 Cursor 的 WSL 插件

• 打开 Windows 端 Cursor，左侧「扩展商店」（Ctrl+Shift+X）；
• 搜索并安装「Remote – WSL」（微软官方插件，与 VSCode 通用）；
• Cursor 默认内置 Python 支持，无需额外安装 Python 插件。

2. 连接 Cursor 到 WSL

• 按下Ctrl+Shift+P打开命令面板，输入「WSL: Connect to WSL」，选择你的 WSL 发行版；
• 连接成功后，Cursor 左下角显示「WSL: Ubuntu-22.04」。

3. 打开 WSL 目录并选择 conda 解释器

• 点击「File → Open Folder」，选择 WSL 中的项目目录（如~/python_project），确认信任；
• 按下Ctrl+Shift+P，输入「Python: Select Interpreter」，选择 conda 环境python_wsl_env；
• Cursor 右下角会显示 conda 环境版本，配置完成。

4. 运行 Python 代码

• 新建test_conda.py（同 VSCode 示例代码）；
• 方式 1：右上角运行：点击编辑区右上角「▶️ Run」，选择「Run Python File in Terminal」，终端输出结果；
• 方式 2：终端运行：打开 Cursor 内置终端（Ctrl+``），激活conda环境后执行python test_conda.py`；
• 方式 3：AI 辅助运行（Cursor 特色）：选中代码→按下Ctrl+L打开 AI 窗口→输入「运行这段代码并验证 conda 环境是否生效」，AI 会执行代码并返回结果 + 环境验证信息。

六、常见问题与解决方案

1. VSCode/Cursor 中找不到 conda 虚拟环境

• 原因：conda 环境未被 VSCode/Cursor 识别，或解释器路径未刷新；
• 解决：
• 确保已在 WSL 终端激活过该 conda 环境；
• 在 VSCode/Cursor 中执行命令面板→「Python: Refresh Interpreter List」刷新列表；
• 手动指定路径：命令面板→「Python: Select Interpreter」→「Enter interpreter path」→输入/home/你的用户名/miniconda3/envs/python_wsl_env/bin/python。

2. WSL 终端中输入 conda 命令提示「command not found」

• 原因：安装 Miniconda 时未选择conda init，环境变量未配置；
• 解决：

  bash

  运行

  # 手动初始化conda
  ~/miniconda3/bin/conda init bash
  # 重启终端，或执行source ~/.bashrc使配置生效
  source ~/.bashrc

3. 运行代码提示「ModuleNotFoundError: No module named 'numpy'」

• 原因：包安装在 base 环境，未安装在当前 conda 环境；
• 解决：激活目标环境后安装：

  bash

  运行

  conda activate python_wsl_env
  conda install numpy -y

4. 终端输出中文乱码

• 解决：在 WSL 终端执行以下命令配置 UTF-8 编码：

  bash

  运行

  echo "export LC_ALL=en_US.UTF-8" >> ~/.bashrc
  echo "export LANG=en_US.UTF-8" >> ~/.bashrc
  source ~/.bashrc

  重启 VSCode/Cursor 的 WSL 终端即可。

5. 激活 conda 环境提示「CommandNotFoundError: Your shell has not been properly configured to use 'conda activate'」

• 原因：shell 未初始化 conda，或使用 zsh 而非 bash；
• 解决：

  bash

  运行

  # 若用bash
  conda init bash
  # 若用zsh（WSL默认是bash，若手动切换过）
  conda init zsh
  # 重启终端

七、总结

按照以上步骤，你可在 WSL 的隔离环境中安全运行 Python 代码，同时利用 VSCode/Cursor 的便捷开发功能（调试、AI 辅助等）。