VS Code 初学者如何配置 Python 虚拟环境并运行第一个项目

内容总结生成中

你看见的，不仅是一个总结

你将用一个最小 Python 项目，在 VS Code 中创建虚拟环境、选择项目解释器、安装依赖并运行脚本。以下步骤适用于 Windows、macOS 和 Linux；开始前请安装 Python 和 VS Code，并在 VS Code 中安装 Microsoft 的 Python 扩展。本文只配置本地项目环境，不涉及 Python 语言入门或项目部署。

1. 创建并打开项目文件夹

先在电脑上新建一个文件夹，例如 hello-python，然后在 VS Code 中选择“文件”>“打开文件夹”，打开它。接下来创建的虚拟环境和脚本都放在这个项目目录中。

打开 VS Code 集成终端：选择“终端”>“新建终端”。终端当前所在位置应是项目文件夹；你也可以输入 pwd（Windows PowerShell 可用 Get-Location）确认路径。

2. 在项目目录中创建虚拟环境

虚拟环境是项目专用的 Python 运行环境。将依赖安装到项目自己的环境里，可以减少不同项目之间的依赖冲突，也避免把项目依赖误装到系统 Python 中。

确认终端位于项目文件夹后，按系统选择一条命令：

# Windows
py -m venv .venv

# macOS 或 Linux
python3 -m venv .venv

命令执行后，项目目录中会出现 .venv 文件夹。里面包含该环境的 Python 和用于安装依赖的工具。通常不需要手动打开或修改其中的文件。

如果 Windows 找不到 py，可尝试：

python -m venv .venv

如果 macOS 或 Linux 找不到 python3，先确认 Python 是否已安装并能从终端调用；具体安装方式取决于你的系统。创建虚拟环境时出现错误，不要继续往系统环境安装依赖，先根据本文末尾的排查方法确认 Python 命令和项目路径。

3. 在 VS Code 中选择项目解释器

创建环境后，按 Ctrl+Shift+P（macOS 通常为 Cmd+Shift+P）打开命令面板，搜索并选择“Python: Select Interpreter”。在列表中选择路径包含项目 .venv 的解释器。

如果列表中没有它，选择“Enter interpreter path”或类似选项，再手动指定解释器：

Windows：项目目录.venvScriptspython.exe
macOS 或 Linux：项目目录/.venv/bin/python

这里选择的解释器决定 VS Code 使用哪个 Python 运行代码。仅仅创建 .venv 并不会自动保证编辑器已选中它，因此需要确认列表里显示的是当前项目的环境。

可在终端运行下面的命令检查解释器路径：

python -c "import sys; print(sys.executable)"

输出路径应包含项目中的 .venv。如果终端提示找不到 python，或输出指向系统 Python，继续下一步前先检查解释器选择；也可以关闭当前终端，再从 VS Code 新建一个终端后重试。

4. 在虚拟环境中安装依赖

安装前先确认终端当前使用的是项目的虚拟环境。然后使用 python -m pip 安装依赖，而不是直接运行可能指向其他 Python 环境的 pip 命令。

例如，下面的命令会在当前环境安装一个示例依赖：

python -m pip install requests

初次练习也可以暂不安装任何依赖：运行标准库中的简单脚本不需要额外安装包。无论是否安装，依赖都应装到当前项目选中的 .venv 中。之后可以用下面的命令查看当前环境里已安装的包：

python -m pip list

如果输出中包含刚安装的包，说明安装命令已执行；但还应确认 python 指向 .venv，否则包可能被装到了另一个环境。

5. 创建并运行第一个脚本

在 VS Code 文件列表中创建 main.py，输入以下代码并保存：

print("Hello, Python!")

在编辑器中打开 main.py，点击右上方的运行按钮，或在终端中输入：

python main.py

成功时，终端会显示：

Hello, Python!

这是最小的成功验证：脚本已运行，并将结果输出到终端。若运行按钮使用了错误的解释器，重新执行“Python: Select Interpreter”，选中项目的 .venv 后再运行。

常见问题与调整方法

终端提示找不到 Python

Windows 可依次尝试 py --version 和 python --version；macOS 或 Linux 可尝试 python3 --version。如果这些命令都无法显示版本，说明终端暂时无法调用 Python。确认 Python 已安装后，重新打开 VS Code 和终端再试；如果仍不行，需要检查本机的 Python 安装或命令路径。

解释器列表没有 `.venv`

确认 .venv 已在当前打开的项目文件夹中创建，并且环境创建命令没有报错。然后重新打开命令面板，选择“Python: Select Interpreter”，必要时手动指定 .venv 中的 Python 可执行文件。

安装成功，但运行时提示找不到模块

通常是安装依赖和运行脚本时使用了不同的 Python 环境。在 VS Code 终端运行：

python -c "import sys; print(sys.executable)"
python -m pip list

第一条命令确认当前解释器路径，第二条查看当前环境中的包。确保解释器路径包含项目的 .venv；若不包含，重新选择项目解释器并新建终端，再使用 python -m pip install 包名 安装所需依赖。

Windows PowerShell 不允许激活环境

手动激活环境不是运行 Python 脚本的必要条件。在 VS Code 中选好 .venv 解释器后，可直接使用 python main.py 和 python -m pip install 包名。如果确实需要激活，PowerShell 的执行策略可能会阻止激活脚本；不要为了解决这个问题随意降低系统安全设置，可改用命令提示符终端，或继续使用 VS Code 选定的解释器。