三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Win11下Python虚拟环境配置指南：VSCode中venv、virtualenv与Conda实战

发布时间：2026/8/17 2:16:15 三亩地 编程学习日记
Win11下Python虚拟环境配置指南：VSCode中venv、virtualenv与Conda实战

1. 为什么在Win11上配置Python虚拟环境是开发者的第一课

如果你刚开始用VScode写Python，或者刚从PyCharm、Jupyter Notebook转过来，大概率会直接在你的系统Python里pip install各种包。头几次可能很顺利，直到某天你接手一个老项目，需要Django 2.2，而你的新项目需要Django 4.0，或者你想试试某个教程的代码，结果pip install把整个环境搞得一团糟，依赖冲突报错让你一头雾水。这时你就需要一个“隔离的工作间”——Python虚拟环境。

在Windows 11上，尤其是用VScode这类轻量但高度可配置的编辑器，配好虚拟环境不是可选项，而是必选项。Win11作为微软的最新桌面系统，其文件路径、终端权限和与开发工具的集成方式与Win10有些许不同，直接套用老教程可能会踩坑。虚拟环境的核心作用就是为每个Python项目创建一个独立的沙箱，里面有自己的Python解释器、pip工具以及独立的第三方库安装目录。项目A用pandas 1.3，项目B用pandas 2.0，两者互不干扰，就像在电脑上开了多个互不影响的独立房间。

我见过很多新手，包括几年前的我，觉得虚拟环境麻烦，跳过这一步。结果就是全局环境越来越臃肿，各种版本冲突层出不穷，最后不得不重装Python，时间成本反而更高。用VScode配合虚拟环境，不仅能实现环境隔离，还能通过编辑器强大的集成终端和状态栏提示，让环境切换变得可视化、自动化，极大提升开发体验和项目可维护性。接下来，我会基于Win11系统，带你从零开始，用几种主流方法在VScode中配置Python虚拟环境，并分享我踩过的一些坑和高效技巧。

2. 环境准备：安装Python与VScode的核心要点

在搭建虚拟环境之前，你得先把“地基”打好，也就是正确安装Python和VScode。这一步看似简单，但很多问题都源于最初的安装配置不当。

2.1 Python安装：别小看那个“Add to PATH”复选框

首先，前往Python官网下载Windows安装包。对于大多数开发，选择最新的稳定版（比如Python 3.11.x）即可。运行安装程序时，你会看到一个至关重要的选项：“Add python.exe to PATH”。

注意：务必勾选这个选项！它的作用是将Python和pip的执行路径添加到系统的环境变量中。这样，你就可以在任意位置的命令行（如CMD、PowerShell）中直接输入python或pip来调用它们，而不需要输入完整的安装路径。很多新手安装后无法在命令行使用python命令，十有八九是因为漏掉了这一步。

安装类型建议选择“Install Now”（使用默认路径）或“Customize installation”进行自定义。自定义安装时，可以勾选“Install for all users”和“Associate files with Python”，后者会将.py文件默认用Python打开。安装路径避免使用包含中文或空格的目录，比如C:\Python311\就是一个好选择。

安装完成后，验证一下。按下Win + R，输入cmd打开命令提示符，或者右键开始菜单选择“Windows终端（管理员）”。输入以下命令：

python --version pip --version

如果这两条命令都能正确返回版本号，说明Python和pip已就位。如果提示“不是内部或外部命令”，则需要手动添加环境变量：在系统设置中搜索“环境变量”，编辑“Path”，添加Python的安装目录（如C:\Python311\）和其Scripts目录（如C:\Python311\Scripts\）。

2.2 VScode安装与必备Python扩展

VScode的安装相对直接，从官网下载安装包，一路下一步即可。安装完成后，为了高效进行Python开发，你需要安装微软官方提供的Python扩展。

  1. 打开VScode，点击左侧活动栏的“扩展”图标（或按Ctrl+Shift+X）。
  2. 在搜索框中输入“python”。
  3. 找到由Microsoft发布的“Python”扩展，点击安装。这个扩展包提供了代码补全、智能感知、 linting、调试、代码导航、格式化、Jupyter笔记本支持等几乎所有你需要的功能，是Python开发的基石。

此外，我强烈建议再安装一个“Pylance”扩展，它是微软新一代的Python语言服务器，在代码补全和类型提示方面比默认的Jedi更强大、更迅速。通常安装Python扩展时会推荐你一并安装。

3. 创建虚拟环境的三种主流方法及其选择逻辑

一切就绪，现在进入核心环节：创建虚拟环境。在Windows上，主要有三种方式，它们各有适用场景。

3.1 使用内置的venv模块（推荐给纯Python项目）

venv是Python 3.3+版本内置的模块，无需额外安装，最适合创建轻量级的、纯Python项目的虚拟环境。它的原理是在项目目录下复制一份Python解释器，并创建一个独立的Lib/site-packages文件夹来存放项目依赖。

操作步骤：

  1. 为你的项目创建一个专属文件夹，例如D:\my_python_project。
  2. 在VScode中，通过文件 -> 打开文件夹，打开这个项目文件夹。
  3. 打开VScode的集成终端（查看 -> 终端或Ctrl+`）。终端默认会在当前项目根目录打开。
  4. 在终端中输入以下命令创建虚拟环境：
    python -m venv .venv
    这里的.venv是虚拟环境文件夹的名字，前面的点号在部分系统上会使其成为隐藏文件夹，这是一种约定俗成的命名方式。你也可以用venv或env。

命令解析：

  • python -m venv：意思是让Python以模块(-m)的方式运行venv这个包。
  • .venv：指定虚拟环境目录的名称。执行后，会在当前目录下生成一个名为.venv的文件夹，里面包含了独立的Python环境。

为什么推荐venv？对于大多数不涉及复杂数据科学库（如需要特定CUDA版本的TensorFlow）的Web开发、脚本编写、自动化任务，venv足够用了。它创建速度快，环境干净，与VScode的集成也最无缝。后续在VScode中选择解释器时，它能被自动识别。

3.2 使用virtualenv第三方工具（更灵活的老牌选择）

virtualenv是一个第三方工具，在venv出现之前是事实上的标准。它比venv更早，功能也更丰富一些，比如可以指定不同版本的Python解释器来创建环境（前提是你已安装多个Python版本）。

操作步骤：

  1. 首先需要安装virtualenv。在终端中运行：
    pip install virtualenv
  2. 安装完成后，在项目根目录下，使用以下命令创建环境：
    virtualenv myenv
    这会在当前目录创建名为myenv的虚拟环境文件夹。

virtualenv与venv如何选择？

  • 如果你需要为同一个项目创建基于不同Python版本（如3.8和3.11）的环境进行测试，virtualenv更方便。
  • 如果你在非常老的系统（Python 3.3之前）上工作，只能用virtualenv。
  • 其他情况下，优先使用内置的venv，减少一个外部依赖。

3.3 使用Conda环境（数据科学与机器学习首选）

如果你的项目涉及机器学习、深度学习，需要管理复杂的非Python依赖（如特定的MKL数学库、CUDA工具包），或者你通过Anaconda发行版安装的Python，那么Conda环境是更好的选择。Conda本身是一个跨平台的包和环境管理器，它不仅能管理Python包，还能管理R、C++等语言的包以及系统级的库。

操作步骤（假设已安装Anaconda或Miniconda）：

  1. 打开“Anaconda Prompt”（这是一个专门为Conda配置的命令行）或VScode的终端（如果VScode能正确识别Conda）。
  2. 在终端中，使用以下命令创建环境并指定Python版本：
    conda create -n my_conda_env python=3.9
    这条命令会创建一个名为my_conda_env、Python版本为3.9的新环境。
  3. 激活环境：
    conda activate my_conda_env

在VScode中使用Conda环境的注意事项：Conda环境的管理和激活逻辑与venv不同。有时VScode无法自动检测到Conda环境，尤其是在Win11上，如果Conda没有正确初始化。你需要在VScode的终端中先运行conda init相关命令，或者手动在VScode的设置中指定Conda可执行文件的路径。对于纯Python开发的新手，我建议先从venv开始，它的路径更清晰，问题更少。

4. 在VScode中激活、选择与管理虚拟环境

创建好虚拟环境文件夹（如.venv）只是第一步，接下来需要“激活”它，并让VScode知道使用这个环境来运行和调试你的代码。

4.1 手动激活虚拟环境

在VScode的集成终端中，你需要激活环境才能使用其中的Python和pip。

  • 对于venv或virtualenv创建的环境： 在项目根目录的终端中，运行：

    # 对于.venv (Windows) .venv\Scripts\activate

    激活后，你会看到终端提示符前面出现了环境名(.venv)，这表示你当前正工作在该虚拟环境中。之后所有pip install的包都会安装到这个环境里，与系统全局环境无关。

  • 对于Conda环境：

    conda activate my_conda_env

4.2 让VScode自动识别并选择解释器（关键步骤）

手动激活在终端里有效，但为了让你在VScode中享受代码补全、linting、调试等功能，必须为当前工作区（项目文件夹）指定正确的Python解释器。

  1. 打开命令面板：按F1或Ctrl+Shift+P。
  2. 输入并选择“Python: Select Interpreter”。
  3. 此时，VScode会扫描当前项目目录以及系统已知的Python环境，并列出所有可用的解释器。你应该能看到一个路径指向你刚创建的虚拟环境，例如：
    • Python 3.11.4 ('.venv': venv)
    • 或者C:\Users\YourName\.conda\envs\my_conda_env\python.exe
  4. 选择这个虚拟环境对应的解释器。

选择后的效果：

  • VScode底部状态栏的左侧会显示当前选择的Python解释器版本和环境名称。
  • 此后，当你使用VScode的“运行”按钮（或按F5调试）、在终端里直接点击代码上方的“运行”三角符号时，VScode都会自动使用你选定的虚拟环境中的Python来执行代码。
  • 即使你没有在终端手动activate，在VScode的集成终端里新建一个终端时，它通常也会自动为你激活当前项目选定的虚拟环境（这是一个非常方便的特性）。

4.3 在激活的环境中安装与管理包

环境激活且VScode识别后，你就可以安装项目所需的包了。确保终端提示符前有(.venv)字样，然后使用pip安装。例如，安装requests和flask：

(.venv) D:\my_python_project> pip install requests flask

为了便于协作和复现，通常我们会将项目依赖记录在一个requirements.txt文件中。

  • 生成依赖列表：在虚拟环境激活状态下，运行pip freeze > requirements.txt，这会生成一个包含所有已安装包及其精确版本的文件。
  • 根据依赖列表安装：在新环境或另一台机器上，拿到requirements.txt后，运行pip install -r requirements.txt即可一键安装所有依赖。

5. 实战配置：从新建项目到运行调试的完整流程

让我们串联起所有步骤，完成一个从零开始的项目配置实战。

  1. 创建项目文件夹：在磁盘上新建D:\demo_app。
  2. 用VScode打开：打开VScode，选择“打开文件夹”，定位到D:\demo_app。
  3. 创建虚拟环境：在VScode中打开终端（Ctrl+`），输入python -m venv .venv。等待创建完成。
  4. 选择解释器：按Ctrl+Shift+P，输入“Python: Select Interpreter”，选择刚刚生成的.venv环境下的Python。
  5. 验证环境：在终端里，你应该能看到自动激活的(.venv)提示。输入python --version和pip list，确认Python版本和干净的pip列表。
  6. 编写代码：在VScode资源管理器中，新建一个app.py文件，输入简单代码：
    import requests response = requests.get('https://httpbin.org/get') print(response.status_code) print("Hello from virtual environment!")
  7. 安装依赖：由于代码用了requests，我们需要安装它。在终端中运行pip install requests。
  8. 运行代码：在app.py文件中右键，选择“在终端中运行Python文件”，或者直接按F5选择“Python File”进行调试。代码应该能成功运行并打印结果。

至此，一个完整的、基于独立虚拟环境的Python项目就在VScode中配置好了。你的所有操作都被限制在这个.venv文件夹内，不会影响系统其他Python项目。

6. 常见问题排查与高效技巧分享

即使按照步骤操作，在Win11上你可能还是会遇到一些特有的问题。这里分享我遇到过的坑和解决办法。

6.1 终端无法激活虚拟环境（执行策略限制）

在PowerShell终端中运行.venv\Scripts\activate时，可能会看到红色错误提示：“无法加载文件…，因为在此系统上禁止运行脚本”。这是因为Win11默认的PowerShell执行策略是Restricted（受限的）。

解决方案：以管理员身份打开Windows终端（或PowerShell），执行以下命令更改执行策略：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

输入Y确认。这个命令将当前用户的执行策略设置为RemoteSigned，允许运行本地脚本和来自可信远程源的签名脚本。完成后，关闭并重新打开VScode的终端，再次尝试激活命令。

注意：RemoteSigned策略在大多数开发场景下是安全的。你也可以使用更宽松的Bypass（仅限当前会话）或更严格的AllSigned，但RemoteSigned是一个良好的平衡点。

6.2 VScode找不到或无法选择虚拟环境解释器

有时点击“选择解释器”后，列表里没有你的.venv环境。

  • 原因1：VScode未正确打开项目根目录。确保你是通过“打开文件夹”的方式打开了包含.venv文件夹的那个目录，而不是只打开了子文件夹或单个文件。
  • 原因2：环境尚未被索引。尝试重启VScode，或者打开命令面板运行“Python: Refresh Python Interpreters”命令来刷新列表。
  • 原因3：虚拟环境创建失败。检查.venv文件夹是否完整，里面是否有Scripts文件夹和python.exe。如果不完整，删除.venv文件夹，重新创建一次。

6.3 包安装慢或失败（配置国内镜像源）

从Python官方的PyPI服务器下载包，在国内速度可能很慢甚至超时。我们可以将pip的源更换为国内镜像站，如清华源、阿里云源。

临时使用：在pip install命令后加-i参数。

pip install pandas -i https://pypi.tuna.tsinghua.edu.cn/simple

永久配置（推荐）：在用户目录（C:\Users\你的用户名\）下创建一个名为pip的文件夹，在里面新建一个pip.ini文件，用记事本打开并写入：

[global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple trusted-host = pypi.tuna.tsinghua.edu.cn

这样以后所有pip install命令都会默认使用清华源，速度飞快。

6.4 高效工作流技巧

  1. 为每个项目单独创建.venv：这是黄金法则。即使两个项目依赖相似，也建议分开，避免日后潜在的版本冲突。
  2. 将.venv添加到.gitignore：虚拟环境文件夹通常很大，且包含系统特定的文件，不应提交到Git仓库。在你的项目根目录创建或编辑.gitignore文件，添加一行.venv/（或venv/、env/）。
  3. 使用VScode工作区设置：如果你希望某个VScode窗口固定使用某个Python解释器，可以配置工作区设置。在项目根目录下会生成一个.vscode/settings.json文件，里面记录了当前工作区的特定设置，包括Python路径。这方便了团队协作时环境的一致性。
  4. 终端自动激活：如果你发现打开新终端时没有自动激活环境，可以检查VScode的设置。搜索“Python: Terminal Activate Environment”，确保它是勾选状态。

配置好一次之后，后续的新项目就是“创建文件夹 -> VScode打开 -> 终端python -m venv .venv-> 选择解释器”的标准流程，熟练后一分钟内就能完成。这个看似微小的习惯，是保持Python开发环境整洁、高效、可复现的基石，越早养成，未来踩的坑就越少。

编程学习 学习日记 实战经验
← 返回列表