VS Code中调试和运行Python脚本的配置指南

Elena

发布时间：2026-10-10 | 2人浏览过

原创

在 Visual Studio Code（VS Code）中正确运行与调试 Python 脚本，核心由三个确定的基础环节构成：安装官方 Python 扩展、为当前工作区精确绑定目标 Python 解释器，以及通过 launch.json 配置文件定义 debugpy 调试引擎的运行参数。只要厘清这三者之间的依赖与数据流向，无论是单文件快速试运行，还是多模块、带参数注入的复杂断点调试，都能获得稳定、可预期的执行结果。

VS Code中调试和运行Python脚本的配置指南 — 图 1：VS Code 中 Python 运行与调试的核心组成与交互关系

一、前置准备与解释器精确绑定

在 VS Code 中开展 Python 开发的第一步，必须安装微软官方提供的 Python 扩展组件（扩展 ID 为 ms-python.python）。该扩展为编辑器提供了 Python 语言服务（基于 Pylance）、测试发现以及基于 debugpy 的调试适配能力。

安装完成后，核心步骤在于为工作区绑定正确的 Python 解释器。许多初学者常遇到的现象是“在系统终端中能执行 python script.py，但在 VS Code 内部运行却报 ModuleNotFoundError”，其根本原因就是编辑器当前绑定的解释器路径与终端实际安装依赖的 Python 环境不一致。

精确选择解释器的操作路径

打开项目文件夹（确保以目录为单位打开工作区，而非仅打开单个孤立文件）。
按下快捷键组合 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）调出命令面板。
输入并选择命令：Python: Select Interpreter（选择解释器）。
在弹出的列表中，VS Code 会自动扫描系统路径、Conda 环境、虚拟环境（如项目根目录下的 .venv 或 venv）。点击选中期望使用的环境。

选择成功后，VS Code 右下角的状态栏会直接显示当前选中的 Python 版本及其虚拟环境名称（例如 Python 3.11.8 ('.venv': venv)）。这表明环境绑定已成功生效。

二、单文件快捷运行与终端交互机制

在没有复杂传参需求时，最简单的运行方式是使用编辑窗口右上角的“运行”按钮。当编辑器处于某个 .py 文件时，点击右上角的播放图标或下拉菜单中的“在专用终端中运行 Python 文件”，VS Code 会自动触发以下内部机制：

在底部面板打开一个集成的系统终端（PowerShell、Bash 或 Zsh）。
自动执行虚拟环境激活命令（例如 source .venv/bin/activate 或 .\.venv\Scripts\Activate.ps1）。
将所选解释器可执行文件与当前打开文件的绝对路径拼接并执行。

注意：右上角“运行”按钮默认仅将当前激活的单个文件作为脚本执行。如果该脚本依赖命令行参数输入（sys.argv 或 argparse），或者依赖特定工作目录相对路径读取资源，使用快捷运行按钮往往会导致参数缺失报错。此时必须引入 launch.json 调试配置。

三、工程化调试核心：launch.json 规范与参数配置

对于专业开发场景，VS Code 依靠 .vscode/launch.json 文件实现调试配置的持久化。通过该文件，可以固化启动参数、环境变量、工作目录、调试模块或附加进程逻辑。

创建 launch.json 文件

点击左侧活动栏的“运行与调试”图标（带虫子与播放箭头的图标，快捷键 Ctrl+Shift+D / Cmd+Shift+D）。点击“创建 launch.json 文件”，在下拉调试器选项中选择 Python Debugger，随后选择 Python 文件（调试当前激活的 Python 文件）。VS Code 会在项目根目录下自动创建 .vscode/launch.json。

以下是一份经过工程化验证的标准 launch.json 配置范例：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: 调试当前文件",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true
    },
    {
      "name": "Python: 固定入口脚本带参调试",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/main.py",
      "args": ["--config", "configs/dev.json", "--epochs", "10"],
      "cwd": "${workspaceFolder}",
      "env": {
        "APP_ENV": "development",
        "LOG_LEVEL": "DEBUG"
      },
      "console": "integratedTerminal",
      "justMyCode": false
    }
  ]
}

关键配置参数解析

参数字段	典型取值	作用与重要约束
`type`	`"debugpy"`	指定使用的调试适配器。新版 VS Code Python 扩展中，统一采用独立的 `debugpy` 类型。
`request`	`"launch"` 或 `"attach"`	`launch` 表示由 VS Code 直接拉起新进程；`attach` 用于连接已在运行的外部 Python 进程。
`program`	`"${file}"` 或绝对路径	入口脚本路径。`${file}` 表示当前聚焦的文件；固定工程项目建议写为 `"${workspaceFolder}/main.py"`。
`args`	`["--arg1", "val1"]`	传给 Python 脚本的命令行参数列表，避免在终端中反复手工敲击参数。
`cwd`	`"${workspaceFolder}"`	执行进程的工作目录。对相对路径（如 `open('data/input.csv')`）的解析具有决定性影响。
`env`	`{"KEY": "VALUE"}`	注入子进程的环境变量字典，便于在本地模拟配置项或 API 凭据。
`justMyCode`	`true` 或 `false`	设为 `true` 时，单步调试会自动跳过标准库和第三方库源码；设为 `false` 时可深入追踪三方包内部调用。

四、三种运行与调试模式的适用边界对比

在日常开发中，开发者通常在“快速运行”、“launch.json 定制调试”以及“终端原生命令”三种模式之间选择。清晰理解它们的适用边界，能显著提升开发效率并避免排错走弯路：

五、断点调试实操流程与调试控制台交互

配置完成 launch.json 之后，即可展开精确的代码行级追踪。以下是完整的调试操作链条：

1. 设立断点类型

常规行断点：在代码行号左侧的灰色边缘处单击，出现一个实心鲜红圆点。程序运行到该行代码之前会自动挂起。
条件断点（Conditional Breakpoint）：右键点击红点并选择“编辑断点”，可输入一个 Python 表达式（例如 i >= 50 或 user_id == 'admin'）。只有当该表达式计算结果为 True 时，程序才会中断。这对于排查大型循环中的特定异常尤为高效。
日志点（Logpoint）：只打印日志而不暂停程序执行。在日志点内容中可以使用花括号读取变量值（例如 处理批次: {batch_id}, 耗时: {elapsed}）。

2. 启动与控制操作

在编辑区打开目标 Python 文件，按下 F5 键（或在“运行与调试”面板点击绿色的播放三角）。VS Code 底部状态栏将变为橙色，顶部弹出浮动调试工具条，包含六个核心按钮：

继续（F5）：恢复代码执行，直到遇到下一个断点或脚本结束。
单步跳过（F10）：执行当前行代码并停在下一行；如果当前行包含函数调用，不会跳入函数内部。
单步调试（F11）：单步进入当前行调用的函数内部。
单步跳出（Shift+F11）：执行完当前函数剩余代码，跳回调用该函数的外层代码处。
重启（Ctrl+Shift+F5 / Cmd+Shift+F5）：销毁当前调试进程并重新拉起。
停止（Shift+F5）：终止 debugpy 调试会话并释放端口与子进程。

3. 变量监视与调试控制台求值

程序命中断点暂停后，左侧面板将展示丰富的运行时状态：

变量（Variables）：展示局部变量（Locals）和全局变量（Globals），支持直接展开字典、列表或类实例，甚至可双击变量值直接在线修改。
监视（Watch）：点击右上角 + 号添加任意 Python 表达式（如 len(records) 或 response.status_code），每当断点暂停时该表达式都会自动重新计算并显示最新值。
调试控制台（Debug Console）：按下快捷键 Ctrl+Shift+Y（macOS 为 Cmd+Shift+Y）可切换至调试控制台。在当前断点上下文环境中，可以直接输入任意 Python 语句并立即回车执行，非常适合即时验证数据清洗逻辑或函数返回值。

六、常见排错与排查闭环

当调试未按预期工作时，通常集中在以下三类典型问题，建议依照对应分支逐一确认：

结语

在 VS Code 中稳定运行与调试 Python 脚本的关键，不在于死记界面按钮的位置，而在于掌握底层“解释器路径绑定”与“launch.json 运行时定义”的协同机制。确保右下角解释器与开发环境完全一致，按需构建清晰的 launch.json 条目，并善用条件断点与调试控制台，即可在面对复杂的数据处理、Web 服务或机器学习任务时，建立起高效而确定的调试与开发流。