在 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. 安装交互步骤（关键）
- 按
Enter阅读许可协议，连续按Space跳过，最后输入yes同意； - 选择安装路径（默认
/home/你的用户名/miniconda3，直接按Enter即可，无需修改）； - 关键：安装完成后，会提示
Do you wish to initialize Miniconda3 by running conda init?，输入yes（自动配置环境变量，避免后续 conda 命令找不到）； - 安装完成后，删除安装脚本（可选）：
rm miniconda.sh。
5. 验证 Miniconda 安装
- 关闭当前 WSL 终端，重新打开（让环境变量生效）；
- 首次启动终端会显示
(base)前缀，说明默认激活了 base 环境（后续可关闭，见下方优化）。
执行以下命令，若输出 conda 版本号则安装成功：bash运行
conda --version # 示例输出：conda 24.5.0 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 虚拟环境（常用命令）
| 操作 | 命令 |
|---|---|
| 激活环境 | conda activate python_wsl_env |
| 退出环境 | conda deactivate |
| 查看所有环境 | conda info --envs 或 conda env list |
| 删除环境（谨慎） | conda remove -n python_wsl_env --all -y |
| 安装包（激活后） | conda install numpy pandas -y |
| 用 pip 安装包（激活后） | pip install requests |
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 种方式）
- 右上角运行按钮：点击编辑区右上角的「▶️」，选择「Run Python File in Terminal」，VSCode 底部会打开 WSL 终端，输出结果（自动激活 conda 环境）；
- 终端手动运行：打开 VSCode 内置终端（
Ctrl+``），先激活conda环境conda activate python_wsl_env，再执行python test_conda.py`； - 断点调试：在代码行号左侧点击添加断点→按下
F5启动调试，可逐行执行、查看变量（自动使用 conda 环境）。
五、方案 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 中 conda 环境的核心是「安装 Miniconda→创建虚拟环境→激活使用」；
- VSCode/Cursor 通过「Remote - WSL」插件连接 WSL 后，选择 conda 环境的 Python 解释器即可无缝运行代码；
- 关键注意：所有包需安装在目标 conda 环境中，而非 base 环境，避免依赖冲突。
按照以上步骤，你可在 WSL 的隔离环境中安全运行 Python 代码，同时利用 VSCode/Cursor 的便捷开发功能（调试、AI 辅助等）。
