VS Code Python 环境配置教程 – wiki基地

---

Visual Studio Code Python 环境配置超详细教程

欢迎来到使用 VS Code 进行 Python 开发的世界！Visual Studio Code (VS Code) 是一款轻量级但功能强大的源代码编辑器，凭借其丰富的扩展生态系统、优秀的性能以及对多种语言的良好支持，已成为全球开发者中最受欢迎的IDE之一。对于 Python 开发者而言，VS Code 提供了从代码编辑、智能提示、代码格式化、代码检查到调试、测试等一站式的解决方案，能够极大地提升开发效率和体验。

本教程将带你一步步配置 VS Code，使其成为你进行 Python 开发的强大伙伴。我们将涵盖安装必备软件、配置核心扩展、掌握虚拟环境、设置代码质量工具以及进行高效调试等关键环节。

前言：为什么选择 VS Code 进行 Python 开发？

在进入配置细节之前，我们先快速了解一下 VS Code 的吸引力所在：

1. 轻量与高性能： 相比传统的重量级IDE（如 PyCharm），VS Code 启动更快，资源占用更少，即便在配置较低的机器上也能流畅运行。
2. 强大的扩展性： 通过安装扩展，VS Code 可以轻松支持几乎所有编程语言和开发技术。其 Python 扩展由微软官方开发和维护，功能强大且更新及时。
3. 优秀的用户体验： 直观的界面、高度可定制的设置、快捷键支持、集成终端等特性使得编码过程更为愉悦。
4. 免费与开源： VS Code 是完全免费且开源的，任何人都可以自由使用和贡献。
5. 集成工具丰富： 内置对 Git 的良好支持，方便进行版本控制；集成的终端使得执行命令行操作无需切换窗口。

了解了这些优势，你将更有动力投入到 VS Code 的 Python 环境搭建中。

章节一：准备工作 – 安装 Python

在配置 VS Code 之前，你的计算机上必须已经安装了 Python。VS Code 的 Python 扩展需要一个 Python 解释器来执行代码、分析代码结构以及运行各种开发工具。

1.1 检查 Python 是否已安装

打开你的终端或命令提示符（Windows 系统推荐使用 PowerShell 或新的 Windows Terminal）：

• 在 Windows 上，搜索 “cmd” 或 “PowerShell” 并打开。
• 在 macOS 或 Linux 上，搜索 “Terminal” 并打开。

输入以下命令并按回车：

bash
python --version

或者有时需要输入：

bash
python3 --version

如果系统输出了 Python 的版本号（例如 Python 3.9.7），说明 Python 已经安装。请注意，现代 Python 开发强烈建议使用 Python 3.6 或更高版本。如果显示找不到命令或版本过旧，你需要安装或更新 Python。

1.2 安装 Python

前往 Python 官方网站 (https://www.python.org/downloads/) 下载适合你操作系统的最新稳定版本安装包。

安装时的关键注意事项：

• Windows： 在安装向导的第一步，务必勾选 “Add Python to PATH” 选项！这会将 Python 添加到系统的环境变量中，方便你在任何地方调用 Python 命令。如果没有勾选，安装完成后可能需要手动配置环境变量，相对麻烦。选择自定义安装可以选择安装路径，但一般默认安装即可。
• macOS/Linux： macOS 自带 Python 2，但通常需要安装 Python 3。你可以从官网下载安装包，或者使用包管理器（如 Homebrew for macOS, apt for Debian/Ubuntu, yum/dnf for CentOS/Fedora）进行安装，包管理器安装更方便管理多个 Python 版本。例如，使用 Homebrew：brew install python。使用 apt：sudo apt update && sudo apt install python3 python3-pip。

安装完成后，重新打开终端，再次运行 python --version 或 python3 --version 确认安装成功并记下版本号。

章节二：安装 Visual Studio Code

如果你的电脑上还没有安装 VS Code，请按照以下步骤进行：

1. 前往 VS Code 官方网站 (https://code.visualstudio.com/)。
2. 网站会自动识别你的操作系统并推荐合适的下载版本（Windows, macOS, Linux）。
3. 下载安装包并运行。
4. Windows： 运行下载的 .exe 文件。安装过程中可以一直点击 “下一步”，接受许可协议，选择安装位置。同样建议勾选 “Add to PATH” 和 “Register Code as editor for supported file types” 以及 “Add ‘Open with Code’ action to Windows Explorer file context menu”。
5. macOS： 下载 .zip 文件，解压后将 “Visual Studio Code.app” 拖拽到 “Applications” 文件夹。
6. Linux： 提供 .deb (for Debian/Ubuntu) 和 .rpm (for Fedora/CentOS/RHEL) 安装包。对于基于 Debian 的系统，可以使用 sudo dpkg -i <file>.deb 安装，如果缺少依赖可以使用 sudo apt --fix-broken install 修复。也可以通过官方提供的仓库进行安装，这样更方便后续更新。

安装完成后，打开 VS Code。你将看到一个欢迎界面。

章节三：安装并配置 Python 扩展

这是配置 VS Code 用于 Python 开发最核心的一步。VS Code 本身只是一个编辑器，真正让它理解和处理 Python 代码的是各种语言相关的扩展。

1. 打开 VS Code。
2. 点击左侧活动栏中的 Extensions 图标（或按下 Ctrl+Shift+X）。
3. 在搜索框中输入 “Python”。
4. 找到由 Microsoft 发布的 Python 扩展（通常是第一个结果，有一个蓝色的 Python Logo）。
5. 点击绿色的 “Install” 按钮进行安装。

安装完成后，通常需要重启 VS Code 来使扩展完全生效。

Python 扩展提供的核心功能：

• IntelliSense： 代码补全、签名帮助、悬停信息、跳转到定义等。
• Linting： 代码静态分析，检查语法错误、潜在问题和风格不一致。
• Formatting： 自动格式化代码，遵循特定的风格规范（如 PEP 8）。
• Debugging： 强大的调试器，支持设置断点、单步执行、查看变量等。
• Testing： 集成测试框架支持（如 unittest, pytest, nose）。
• Jupyter Notebooks： 直接在 VS Code 中创建、编辑和运行 Jupyter Notebook。
• Refactoring： 代码重构功能。

章节四：掌握虚拟环境（Virtual Environments）

虚拟环境是 Python 开发中一个极其重要的概念，它能帮助你隔离不同项目所需的依赖库，避免版本冲突。强烈建议为每一个 Python 项目创建一个独立的虚拟环境。

4.1 为什么需要虚拟环境？

想象一下你有两个 Python 项目：

• 项目 A 需要 requests 库的版本 2.20.0。
• 项目 B 需要 requests 库的版本 2.28.0。

如果你将所有库都安装在全局 Python 环境中，就会出现冲突：requests 只能是其中一个版本。而虚拟环境为每个项目提供了一个独立的 Python 解释器和独立的 site-packages 目录，这样项目 A 的虚拟环境可以安装 requests 2.20.0，项目 B 的虚拟环境可以安装 requests 2.28.0，互不影响。

常见的虚拟环境工具有：

• venv： Python 3.3+ 内建的工具，轻量且无需额外安装。
• virtualenv： 历史更久，功能更多，支持更早的 Python 版本，但通常 venv 已经足够。
• Conda： 主要用于科学计算领域，不仅管理 Python 包，还能管理非 Python 的系统级依赖，功能强大但相对重量级。

本教程主要介绍使用内建的 venv，因为它最常用且简单。

4.2 使用 venv 创建和激活虚拟环境

1. 打开项目文件夹： 在 VS Code 中，通过 File > Open Folder... 打开你的 Python 项目所在的文件夹。
2. 打开集成终端： 在 VS Code 中，点击 Terminal > New Terminal (或按下 Ctrl+ 反引号键 `)。终端会自动进入你当前打开的项目文件夹路径。

3. 创建虚拟环境： 在终端中输入以下命令。我们习惯将虚拟环境命名为 .venv 或 venv，并放在项目根目录下。

   bash
python -m venv .venv
   或者如果你系统同时有 python2 和 python3，并且 python 命令指向 python2，那么使用：
   bash
python3 -m venv .venv
   这条命令会在当前目录下创建一个名为 .venv 的文件夹，里面包含了独立的 Python 解释器、pip 以及相关的脚本。

4. 激活虚拟环境： 创建环境后，你需要激活它才能在当前终端中使用该环境的 Python 和安装的库。激活命令取决于你的操作系统和使用的终端类型：

   • Windows (Command Prompt):
     bash
.venv\Scripts\activate
   • Windows (PowerShell):
     bash
.venv\Scripts\Activate.ps1
   • macOS/Linux (Bash/Zsh):
     bash
source .venv/bin/activate

   激活成功后，你会看到终端提示符前面多了一个 (.venv) 或其他指示符，表明你当前正处于名为 .venv 的虚拟环境中。

5. 安装项目依赖： 在虚拟环境激活的状态下，使用 pip 安装项目所需的库：

   bash
pip install package1 package2 ...
   如果你的项目有 requirements.txt 文件列出了所有依赖，可以在项目根目录下运行：
   bash
pip install -r requirements.txt

6. 生成 requirements.txt (可选，推荐): 当你在项目中安装了新的库后，为了方便其他人或你在其他环境重现相同的依赖，可以生成 requirements.txt 文件：

   bash
pip freeze > requirements.txt

7. 退出虚拟环境： 完成工作后，如果你想回到系统的全局 Python 环境，在终端中输入：

   bash
deactivate

4.3 VS Code 中选择和使用虚拟环境

VS Code 的 Python 扩展能够检测到你创建的虚拟环境，并允许你轻松切换。确保 VS Code 使用了你为当前项目创建的虚拟环境，这一点至关重要！ 否则，IntelliSense 可能找不到你安装的库，调试器也可能无法运行你的代码。

1. VS Code 自动检测： 当你在 VS Code 中打开一个包含虚拟环境（如 .venv 文件夹）的项目时，VS Code 通常会在右下角的状态栏显示当前选择的 Python 解释器。如果它检测到新的虚拟环境，可能会弹出提示询问是否选择它。
2. 手动选择解释器： 如果状态栏没有显示正确的解释器，或者你想切换到其他环境，可以使用命令面板：
   • 按下 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS) 打开命令面板。
   • 输入 “Python: Select Interpreter”。
   • VS Code 会列出它检测到的所有 Python 解释器，包括系统安装的、conda 环境以及项目目录下的虚拟环境。选择你刚刚创建的 .venv 虚拟环境中的那个解释器（通常会显示路径）。

选择正确的解释器后，VS Code 的所有 Python 功能（IntelliSense, Linting, Debugging 等）都会作用于该虚拟环境，从而正确识别你安装的库。状态栏也会更新显示当前选择的解释器。

章节五：编写和运行 Python 代码

配置好环境后，就可以开始编写代码了。

1. 创建 Python 文件： 在 VS Code 中，通过 File > New File 或在文件资源管理器视图中右键点击文件夹选择 “New File”，创建一个以 .py 为后缀的文件（例如 main.py）。
2. 编写代码： 在编辑器中输入你的 Python 代码。你会立即体验到 Python 扩展提供的智能提示 (IntelliSense)、语法高亮等功能。
3. 运行代码：
   • 通过编辑器右上角的“运行”按钮： 打开一个 Python 文件后，在编辑器的右上角会有一个绿色的播放按钮 ▶。点击它可以直接运行当前文件。输出会显示在 VS Code 内置的终端中。
   • 通过右键菜单： 在编辑器中右键点击，选择 “Run Python File in Terminal”。这会在集成终端中执行 python your_file.py 命令。
   • 通过集成终端： 打开集成终端 (Ctrl+反引号`），确保你处于已激活的虚拟环境中，然后手动输入命令 python your_file.py 执行。

章节六：调试 Python 代码

调试是解决代码问题的重要手段。VS Code 提供了强大的图形化调试界面。

1. 设置断点： 在你想要程序暂停执行的代码行左侧的空白区域点击。会出现一个红色圆点，表示设置了断点。

2. 启动调试：

   • 点击左侧活动栏中的 Run and Debug 图标（一个带虫子的播放按钮，或按下 Ctrl+Shift+D）。
   • 点击顶部的绿色播放按钮旁边的下拉箭头，通常 VS Code 会自动检测并提供几种调试配置，例如 “Python File”。选择它，或者点击 “create a launch.json file” 创建一个。
   • 如果你创建了 launch.json，选择 “Python: Current File” 或其他适合你项目的配置。
   • 点击绿色的播放按钮启动调试。

3. 调试界面： 启动调试后，VS Code 界面会切换到调试视图，顶部会出现一个调试控制条，左侧是变量、监视、调用堆栈和断点面板。

   • 调试控制条： 提供继续 (F5)、单步跳过 (F10)、单步调试 (F11)、单步跳出 (Shift+F11)、重启 (Ctrl+Shift+F5)、停止 (Shift+F5) 等操作。
   • 变量 (Variables)： 显示当前作用域内的变量及其值。
   • 监视 (Watch)： 可以添加你想要持续监控的变量或表达式。
   • 调用堆栈 (Call Stack)： 显示当前执行点是通过哪些函数调用路径到达的。
   • 断点 (Breakpoints)： 列出你设置的所有断点，可以启用或禁用它们。
   • 调试控制台 (Debug Console)： 可以在程序暂停时执行 Python 代码，查看变量值，测试表达式等。

4. 单步执行： 使用调试控制条上的按钮或对应的快捷键，你可以逐行执行代码，观察变量值的变化，从而定位问题。

章节七：提升代码质量 – Linters 和 Formatters

好的代码不仅要能工作，还要易于阅读和维护。Linters（代码检查器）帮助你发现潜在的错误、bug 或风格问题；Formatters（代码格式化工具）则自动按照一套规则统一你的代码风格。

7.1 配置 Linters

Python 扩展支持多种 Linter，如 Pylint, flake8, mypy 等。你需要先在当前虚拟环境中安装它们。

1. 安装 Linter： 打开集成终端，激活你的虚拟环境，然后安装你选择的 Linter。例如，安装 Pylint 和 flake8：
   bash
pip install pylint flake8
2. 启用和配置 Linter：
   • 打开 VS Code 设置：File > Preferences > Settings (Windows/Linux) 或 Code > Preferences > Settings (macOS) (快捷键 Ctrl+, 或 Cmd+,)。
   • 在搜索框中输入 python linting。
   • 勾选 Python > Linting: Enabled 选项。
   • 选择你想要使用的 Linter，例如 Python > Linting: Pylint Enabled 和 Python > Linting: Flake8 Enabled。你可以同时启用多个。
   • 如果 Linter 没有被 VS Code 找到，你可能需要指定其路径，但如果安装在当前虚拟环境且解释器选择正确，通常不需要。
   • VS Code 会在代码中用波浪线或下划线标记出 Linter 发现的问题，并在 “Problems” 面板 (View > Problems 或 Ctrl+Shift+M) 中详细列出。

Linters 通常有很多可配置的规则，你可以在项目根目录或用户家目录下创建 Linter 的配置文件（如 .pylintrc, .flake8) 来定制这些规则。

7.2 配置 Formatters

Python 扩展支持多种 Formatter，如 autopep8, Black, Yapf。同样，你需要先在当前虚拟环境中安装它们。Black 是目前非常流行的 Python 格式化工具，以其不妥协的风格著称。

1. 安装 Formatter： 打开集成终端，激活你的虚拟环境，然后安装你选择的 Formatter。例如，安装 Black：
   bash
pip install black autopep8
2. 启用和配置 Formatter：
   • 打开 VS Code 设置 (Ctrl+, 或 Cmd+,)。
   • 在搜索框中输入 python formatting provider。
   • 选择你想要使用的 Formatter，例如将 Python > Formatting: Provider 设置为 black 或 autopep8。
   • 为了在保存文件时自动格式化代码，搜索 editor format on save。
   • 勾选 Editor: Format On Save 选项。

现在，当你保存 Python 文件时 (Ctrl+S 或 Cmd+S)，VS Code 会自动使用你配置的 Formatter 格式化你的代码。

章节八：其他有用的配置和扩展

VS Code 的强大之处还在于其丰富的扩展生态系统和灵活的配置选项。

• Git 集成： VS Code 内置了强大的 Git 支持。左侧活动栏中的 Source Control 图标可以方便地查看文件状态、提交、拉取、推送、分支管理等。
• Jupyter Notebook 支持： Python 扩展自带 Jupyter 支持。直接创建或打开 .ipynb 文件即可在 VS Code 中编辑和运行 Notebook。
• 主题和图标： 通过 Extensions 视图搜索 “theme” 或 “icon theme” 可以安装各种漂亮的代码主题和文件图标，让你的编辑器更个性化。推荐 “Material Icon Theme” 和 “One Dark Pro” 等。
• Settings Sync： 如果你有多台电脑使用 VS Code，可以通过 Settings Sync 同步你的设置、扩展、快捷键等，保持一致的开发环境。在左下角账户图标里启用。
• 其他常用 Python 扩展：
  • indent-rainbow: 用颜色区分缩进层级。
  • Better Comments: 使用不同颜色标记不同类型的注释（TODO, FIXME, etc.）。
  • Docker: 如果你的项目涉及 Docker。
  • GitLens: 增强的 Git 功能，如显示每行代码的最近提交信息。

章节九：常见问题与故障排除

在配置或使用过程中，你可能会遇到一些问题。以下是一些常见问题及其解决方案：

1. “Linter/Formatter <工具名> is not installed” 错误提示：

   • 原因： 你在 VS Code 设置中启用了某个 Linter 或 Formatter，但在当前选择的 Python 解释器（虚拟环境）中没有安装它。
   • 解决： 打开集成终端，激活 VS Code 状态栏显示的虚拟环境，然后使用 pip install <工具名> 命令安装对应的库。

2. IntelliSense (代码补全/提示) 不工作或不准确：

   • 原因： VS Code 可能没有使用正确的 Python 解释器，导致找不到你安装的库；或者 IntelliSense 引擎出现问题。
   • 解决：
     • 检查并重新选择解释器： 确保 VS Code 状态栏显示的是你项目所在的虚拟环境的解释器。如果不是，使用 Ctrl+Shift+P -> “Python: Select Interpreter” 重新选择。
     • 等待分析： 切换解释器后，VS Code 需要时间重新分析代码和库。请耐心等待。
     • 重启 VS Code： 有时简单的重启可以解决问题。
     • 强制刷新 IntelliSense 缓存： 使用 Ctrl+Shift+P -> “Developer: Reload Window”。

3. ModuleNotFound error：

   • 原因： 你的代码导入了某个模块，但在当前运行代码的 Python 环境中没有安装这个模块。
   • 解决：
     • 检查 VS Code 选择的解释器： 确保它指向你的虚拟环境。
     • 检查终端使用的环境： 如果你在终端中手动运行代码，确保终端已经激活了正确的虚拟环境。
     • 安装模块： 在已激活的虚拟环境终端中使用 pip install <模块名> 安装所需的模块。

4. Debugger 不启动或遇到问题：

   • 原因： launch.json 配置错误，或者 Python 解释器路径问题。
   • 解决：
     • 简化配置： 尝试删除 .vscode/launch.json 文件，让 VS Code 使用默认的 “Python: Current File” 配置。
     • 检查解释器： 确保选择了正确的 Python 解释器。
     • 查看输出： 查看 Debug Console 或 VS Code 的 Output 面板（选择 Python Debugger）是否有错误信息。

5. VS Code 运行缓慢或占用资源过多：

   • 原因： 可能安装了过多的扩展，或者在超大文件中工作。
   • 解决：
     • 禁用不常用的扩展： 在 Extensions 视图中禁用一些暂时不需要的扩展。
     • 排除文件： 在设置中配置 files.exclude 或 search.exclude 排除一些不需要 VS Code 索引的文件夹（如大型数据集、编译输出目录等）。
     • 检查后台进程： 检查任务管理器或活动监视器，看是 VS Code 主进程还是某个扩展进程占用了大量资源。

结论

恭喜你！通过遵循本教程的步骤，你已经成功配置了一个功能完善的 VS Code Python 开发环境。从安装 Python 到配置核心扩展、掌握虚拟环境、利用 Linter 和 Formatter 提升代码质量，再到学会使用强大的调试器，你现在已经具备了在 VS Code 中高效进行 Python 开发的基础。

VS Code 的世界还有很多可以探索的地方，例如任务 runner、代码片段、多光标编辑等高级功能。随着你在 Python 开发道路上的不断前进，你会发现 VS Code 及其丰富的扩展生态系统能提供持续的支持和便利。

记住，熟练的工具使用需要实践。现在就开始你的项目，享受在 VS Code 中编写 Python 代码的乐趣吧！

---