VS Code 配置 Python 开发

Visual Studio Code（简称 VS Code）是目前使用最广泛的跨平台代码编辑器。借助微软官方维护的 Python 扩展、Pylance 语言服务器与 Ruff 代码检查工具，它可以被打造成一个接近 IDE 的 Python 开发环境，且启动快、占用低、免费开源。本节将从零开始完成 VS Code 的 Python 环境配置。

前置知识

阅读本节前，建议先了解：IDLE 与交互式解释器，熟悉 Python 的基本运行方式。

基础概念

VS Code 本身只是一个编辑器内核，其能力来自扩展（Extension）。Python 开发涉及三类扩展：

术语	英文	作用
Python 扩展	Python Extension	提供运行、调试、测试、环境管理等基础能力
Pylance	Pylance	基于语言服务器协议（LSP, Language Server Protocol）的类型检查与智能补全
Ruff	Ruff	用 Rust 编写的高速 Linter 与格式化工具
工作区	Workspace	一个被打开的文件夹，配置以它为单位生效
解释器	Interpreter	当前工作区选中的 Python 可执行文件
虚拟环境	Virtual Environment	项目级依赖隔离目录，通常为 .venv

理解「编辑器 + 语言服务器 + Linter」的分层很重要：编辑体验由语言服务器提供，代码质量由 Linter 把关，运行与调试由 Python 扩展驱动，三者可以独立替换。

语法与用法

安装 VS Code

# macOS（Homebrew）
brew install --cask visual-studio-code

# Windows（winget）
winget install Microsoft.VisualStudioCode

# Ubuntu/Debian（官方 apt 源）
sudo apt-get install -y wget gpg
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -D -o root -g root -m 644 packages.microsoft.gpg /etc/apt/keyrings/packages.microsoft.gpg
sudo sh -c 'echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
sudo apt-get update && sudo apt-get install -y code

安装必需扩展

扩展可以通过界面安装，也可以直接用命令行（code CLI）：

# Python 与智能提示
code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance

# Ruff 检查与格式化（新版已合并 lint/format 能力）
code --install-extension charliermarsh.ruff

# 其他常用
code --install-extension ms-python.debugpy
code --install-extension njpwerner.autodocstring

# 查看已安装扩展
code --list-extensions | grep -i python

选择解释器

打开项目文件夹后，按下 Ctrl + Shift + P（macOS 为 Cmd + Shift + P）打开命令面板，输入并执行：

Python: Select Interpreter

也可以点击右下角状态栏的 Python 版本号进行切换。推荐为每个项目创建独立的 .venv：

# 在项目根目录创建虚拟环境
python3 -m venv .venv

# macOS / Linux 激活
source .venv/bin/activate

# Windows PowerShell 激活
.venv\Scripts\Activate.ps1

详细说明

settings.json 配置

工作区配置位于 .vscode/settings.json，与项目一起提交到版本库；用户级配置则通过「命令面板 → Preferences: Open User Settings (JSON)」打开。

推荐的工作区配置示例：

{
  // 可选：显式指定解释器。macOS/Linux 用 bin/python，
  // Windows 需改为 .venv\\Scripts\\python.exe；
  // 若团队跨平台，建议注释掉此行，改用 Python: Select Interpreter 记忆选择
  // "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",

  // 保存时自动格式化并修复问题
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.ruff": "explicit",
    "source.organizeImports.ruff": "explicit"
  },

  // 使用 Ruff 同时承担格式化与检查
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnType": false,
    "editor.rulers": [88]
  },

  // Pylance 类型检查强度
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.autoImportCompletions": true,

  // 终端与测试
  "python.terminal.activateEnvironment": true,
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,

  // 隐藏缓存目录，保持资源管理器整洁
  "files.exclude": {
    "**/__pycache__": true,
    "**/.pytest_cache": true,
    "**/.ruff_cache": true,
    "**/*.pyc": true
  }
}

Windows 用户注意路径

Windows 下虚拟环境的解释器路径为 ${workspaceFolder}\\.venv\\Scripts\\python.exe，且 JSON 中需要转义反斜杠。更稳妥的做法是不写死该字段，依赖 VS Code 的选择记忆。

launch.json 调试配置

调试配置存放在 .vscode/launch.json。VS Code 的 Python 调试器在启动时会自动读取项目根目录的 .env 文件，因此可用它注入环境变量。

一个覆盖常见场景的配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      // 调试当前打开的脚本
      "name": "Python: 当前文件",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true,
      // 注入项目环境变量
      "envFile": "${workspaceFolder}/.env"
    },
    {
      // 以模块方式启动，适合包项目
      "name": "Python: 模块 main",
      "type": "debugpy",
      "request": "launch",
      "module": "myapp.main",
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal",
      "args": ["--debug", "--port", "8000"]
    },
    {
      // 调试 pytest 测试
      "name": "Python: 调试测试",
      "type": "debugpy",
      "request": "launch",
      "module": "pytest",
      "args": ["${file}", "-v", "-s"],
      "console": "integratedTerminal",
      "justMyCode": false
    },
    {
      // 附加到已运行的进程
      "name": "Python: 附加到进程",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5678 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}", "remoteRoot": "/app" }
      ]
    }
  ]
}

配套的 .env 文件示例：

# 调试时注入的环境变量
DEBUG=true
LOG_LEVEL=DEBUG
PYTHONUNBUFFERED=1

调试操作快捷键

F5 启动/继续，F9 切换断点，F10 单步跳过，F11 单步进入，Shift + F5 停止，Ctrl + Shift + Y 打开调试控制台。

多根工作区与任务

如果项目包含多个子包，可用 .vscode/tasks.json 定义常用命令：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "ruff: check",
      "type": "shell",
      "command": "ruff check .",
      "group": "test",
      "problemMatcher": []
    },
    {
      "label": "pytest",
      "type": "shell",
      "command": "pytest -q",
      "group": { "kind": "test", "isDefault": true },
      "problemMatcher": []
    },
    {
      "label": "uv: sync",
      "type": "shell",
      "command": "uv sync",
      "group": "build",
      "problemMatcher": []
    }
  ]
}

之后通过 Ctrl + Shift + P → Tasks: Run Task 即可一键执行。

智能补全与类型检查

Pylance 的检查强度由 python.analysis.typeCheckingMode 控制：

取值	严格度	适用场景
off	关闭	不关心类型问题
basic	基础	日常开发默认推荐
strict	严格	库开发、追求类型完备

在 basic 模式下，Pylance 会标记明显错误（如调用不存在的属性），但不会为每个缺少类型注解的函数报警。若要精细控制，可在 pyrightconfig.json 或 pyproject.toml 的 [tool.pyright] 中配置：

# pyproject.toml
[tool.pyright]
include = ["src"]
exclude = ["**/node_modules", "**/__pycache__", ".venv"]
pythonVersion = "3.12"
typeCheckingMode = "basic"
reportMissingImports = true
reportUnusedImport = "warning"

实战示例

案例一：为一个 Flask 项目配置完整开发环境

项目结构：

flask-demo/
├── .vscode/
│   ├── settings.json
│   └── launch.json
├── .env
├── src/
│   └── app.py
├── tests/
│   └── test_app.py
└── pyproject.toml

初始化环境：

cd flask-demo
python3 -m venv .venv
source .venv/bin/activate
pip install flask pytest

src/app.py：

"""最小 Flask 应用，用于演示 VS Code 调试"""

from flask import Flask, jsonify

app = Flask(__name__)


@app.get("/health")
def health() -> tuple:
    """健康检查接口"""
    return jsonify({"status": "ok", "version": "1.0.0"}), 200


if __name__ == "__main__":
    # 调试时关闭 reloader，避免与断点冲突
    app.run(host="127.0.0.1", port=8000, debug=True, use_reloader=False)

对应的 launch.json 配置片段：

{
  "name": "Flask: 运行 app",
  "type": "debugpy",
  "request": "launch",
  "module": "flask",
  "env": { "FLASK_APP": "src/app.py", "FLASK_DEBUG": "1" },
  "args": ["run", "--no-reload"],
  "jinja": true,
  "cwd": "${workspaceFolder}"
}

按 F5 后在 health() 内打断点，用浏览器访问 http://127.0.0.1:8000/health 即可命中。

案例二：用 Ruff 统一代码风格并接入保存自动修复

pyproject.toml 中配置 Ruff：

[tool.ruff]
line-length = 88
target-version = "py312"

[tool.ruff.lint]
# E/W: pycodestyle, F: pyflakes, I: isort, B: bugbear
select = ["E", "W", "F", "I", "B", "UP"]
ignore = ["E501"]

[tool.ruff.lint.per-file-ignores]
# 测试文件允许使用 assert 与未使用变量
"tests/**" = ["S101", "F841"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

命令行验证：

# 检查
ruff check .

# 自动修复
ruff check --fix .

# 格式化
ruff format .

配合前文的 editor.codeActionsOnSave，保存文件时会自动整理导入并修复可自动修复的问题，团队协作时无需再争论格式。

案例三：Jupyter Notebook 支持

若需要做数据分析，安装 Jupyter 扩展后即可直接在 .ipynb 中运行代码：

code --install-extension ms-toolsai.jupyter
pip install ipykernel pandas matplotlib

在 Notebook 中通过右上角的「选择内核」切换到项目 .venv，即可保证 Notebook 与脚本使用同一套依赖。

注意事项

• 不要用 VS Code 打开单文件而是打开文件夹：Python 扩展的多数功能（解释器选择、调试、测试）以工作区为单位，单文件模式下会退化。
• .vscode/settings.json 中的解释器路径不要写死：团队成员操作系统不同，写死路径会导致他人打开即报错。
• 格式化与检查交给同一套工具：同时启用 Black 与 Ruff format 会产生冲突，二选一即可。
• justMyCode 会跳过库代码：调试第三方库时需要设为 false。
• 调试时避免开启热重载：Flask/Django 的自动重启会让断点失效，调试配置中应显式关闭。

常见问题排查表：

现象	原因	解决
没有补全与跳转	Pylance 未安装或未选解释器	安装 Pylance 并执行 Python: Select Interpreter
导包报红但能运行	解释器指向了全局环境	切换为 .venv 中的解释器
断点显示为空心圆	断点未绑定到代码	确认调试配置的运行路径与实际执行文件一致
debugpy 启动慢	首次构建索引	属正常现象，后续会缓存
Ruff 与 Pylance 同时报错	检查规则重叠	关闭 Pylance 的 lint 或统一到 Ruff

最佳实践

• 统一使用 .venv 目录名：IDE、gitignore 模板、CI 脚本都会默认识别它。
• 把 .vscode/settings.json 提交到仓库：让全团队共享格式化与 lint 规则；但 launch.json 中的机器相关路径宜用变量。
• 配置 editor.rulers 与 line-length 保持一致：避免视觉线与实际规则打架。
• 用工作区推荐扩展：在 .vscode/extensions.json 中声明推荐扩展，新成员打开项目时会被提示安装。

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "charliermarsh.ruff"
  ]
}

• 将 Ruff 检查接入 CI：本地自动修复只是便利，CI 才是质量闸门，详见 Linter 与代码检查工具。
• 定期更新扩展：Python 扩展与 Pylance 迭代频繁，新版本会带来性能与功能改进。

下一节

继续学习：PyCharm 使用指南

参考链接

• VS Code 官方文档 - Python
• VS Code 官方文档 - 调试配置 launch.json
• Pylance 官方文档
• Ruff 官方文档 - VS Code 集成