VSCode Python 调试配置：launch.json 与断点技巧

用 VSCode 写 Python，最容易被忽略、又最影响日常效率的环节，就是 Debug 调试配置。我见过太多人把 VSCode 当成一个"好看点的记事本"——写代码靠它，定位问题还是回到最原始的方式：满屏 print，改一次跑一次，跑完再删。这套打法在脚本只有几十行时没毛病，但只要项目稍微长大一点，涉及多文件导入、异步回调、第三方库内部报错，print 就会立刻变成体力活。这篇文章我想把 VSCode 里 Python 的 Debug 调试配置从头讲透：launch.json 每个字段到底管什么、六类典型场景怎么配、条件断点和日志断点怎么用、断点变灰和 ModuleNotFoundError 这类老毛病怎么排查。不管你是刚装好 Python 的新手，还是写了几年的老手，应该都能从里面抄到可以直接用的配置。

1. 调试这件事，先建立正确的认知框架

很多人上手调试配置时，第一反应是去网上搜一段 launch.json 复制过来，能跑就行。结果一旦换个项目、换个启动方式，就又不会了。问题出在没有建立"调试器是怎么工作的"这层认知。VSCode 本身不是调试器，它只是一个前端界面，真正干活的是后端的调试适配器 Python Debugger（底层是 debugpy）。VSCode 负责画界面、收按键，debugpy 负责在 Python 进程里下断点、读变量、控制执行流。理解了这一层，后面所有配置字段你都能自己推理出来该填什么。

1.1 print 为什么在真实项目里会失效

print 的本质是把状态"打印"到标准输出，它是单向的、事后的、静态的。你只能看到你事先想到要打的那几个变量，出了问题再回去加 print，加完重跑。而断点调试是双向的、实时的、可交互的：程序停在某一行，你可以当场查看整个作用域的变量、修改值、手动调用函数、逐行往下走。举个最常见的例子，一个列表推导式里算错了，print 只能告诉你最终结果，而断点能让你停在那行，直接展开每个中间对象的取值。更别提线上偶发的空指针，靠 print 复现十次可能都碰不到一次。

1.2 VSCode 调试的三种启动方式

VSCode 里启动 Python 调试大致有三条路，理解它们的区别很关键。第一种是直接按 F5，如果没配 launch.json，VSCode 会弹一个环境选择菜单，让你选"Python 文件"还是"模块"等，选完它会自动生成一份基础配置。第二种是手动在.vscode/launch.json里写好配置，按配置名启动，这是最推荐的方式，因为配置可以随项目提交到仓库，团队里每个人拿到就能用。第三种是"附加"（attach）模式，程序已经在跑，你让调试器挂上去，常用于 Web 应用常驻进程、容器内进程。三种方式的request字段分别是launch、launch、attach，这是最核心的区别。

提示：launch是调试器帮你把 Python 进程拉起来；attach是进程已经存在，调试器贴上去。搞混这两个，是很多"配了没反应"的根源。

2. 环境准备：把最小可跑的调试闭环搭起来

在动 launch.json 之前，先把地基打好。我实际带新人时发现，十次调试失败里有三四次根本不是配置问题，而是解释器和扩展没装对。这一步花五分钟，能省掉后面半小时的抓瞎。

2.1 Python 解释器与必需扩展

首先确认本机有可用的 Python，命令行里敲python --version或python3 --version能看到版本号即可。然后在 VSCode 扩展面板里装两个东西：Python（ms-python.python）和Python Debugger（ms-python.debugpy）。前者提供语言服务、解释器选择、测试集成，后者才是提供调试能力的核心。有些老教程还在提 ptvsd，那已经是历史包袱了，现在的调试后端统一是 debugpy，装新扩展就行。

装完扩展，按Ctrl+Shift+P打开命令面板，输入Python: Select Interpreter，选中你项目要用的解释器。如果你用了虚拟环境或者 conda，这里一定要选到虚拟环境里的那个解释器，而不是系统全局的。选错解释器最典型的症状是：代码里明明装了 requests，一调试就报 ModuleNotFoundError。

2.2 生成第一份 launch.json

打开一个 Python 文件，点左侧活动栏的"运行和调试"图标（或者按Ctrl+Shift+D），点击"创建 launch.json 文件"，在弹出列表里选Python File。VSCode 会在项目根目录生成.vscode/launch.json，内容大概是这样：

{ "version": "0.2.0", "configurations": [ { "name": "Python: 当前文件", "type": "debugpy", "request": "launch", "program": "${file}", "console": "integratedTerminal" } ] }

这份配置已经能覆盖 80% 的单文件调试场景。program里的${file}是预定义变量，意思是"当前打开的这个文件"，所以你切到哪个 py 文件，F5 就调试哪个。console设为integratedTerminal，好处是输入输出都走集成终端，input()也能正常接收键盘输入。

2.3 调试工具栏与必背快捷键

启动调试后，顶部会浮出一排按钮：继续、单步跳过、单步进入、单步跳出、重启、停止。它们对应的快捷键建议直接背下来，用熟了效率提升非常明显：

注意：F10 和 F11 别搞反。想快速掠过一批不关心的库代码用 F10，想钻进自己写的函数里查逻辑用 F11，进去之后用 Shift+F11 出来。

3. launch.json 核心字段逐个拆解

这一节是重点。你可能见过别人的 launch.json 里字段一大堆，其实真正常用的就那么几个。我把它们分成"必改"和"看场景改"两类，逐个说清楚它在干什么、什么时候要动它。

3.1 决定程序如何被拉起的字段

program指定要调试的入口文件，写相对路径或配合${workspaceFolder}使用。注意它是文件夹路径下的文件，不是模块名。module则是另一种启动方式，值填模块名（比如flask、pytest），调试器会用python -m 模块名的方式启动，适合包结构清晰的项目。这两个字段通常二选一。

args用来传命令行参数，是个数组。比如你的脚本要接受一个文件路径，就写"args": ["--input", "data.csv"]。cwd是工作目录，默认是项目根${workspaceFolder}，如果你的代码依赖相对路径读文件，cwd 设错就会到处 FileNotFoundError。

python字段可以显式指定解释器路径，当你不想依赖全局选择、或者一个项目要跑多个环境时很有用：

{ "name": "Python: 指定解释器", "type": "debugpy", "request": "launch", "program": "${workspaceFolder}/main.py", "python": "${workspaceFolder}/.venv/bin/python", "cwd": "${workspaceFolder}", "console": "integratedTerminal" }

Windows 下虚拟环境解释器路径是.venv\\Scripts\\python.exe，Linux/macOS 是.venv/bin/python，这个区别经常把人绊住，写配置时记得按平台改。

3.2 环境变量、输出与子进程控制

env和envFile用来注入环境变量。前者直接写在配置里，后者指向一个.env文件，适合放密钥、数据库地址这类不想写进 json 的内容：

{ "env": { "DEBUG": "1", "LOG_LEVEL": "info" }, "envFile": "${workspaceFolder}/.env" }

stopOnEntry设成true时，程序启动后会立刻在第一行停住，适合你想从最开头一步步跟着走的情况。redirectOutput打开后会把输出汇总到调试控制台，但会和input()冲突，一般配合internalConsole用。subProcess设为true时，调试器会尝试追踪子进程，多进程场景下很有用，但它只支持launch模式且不能和attach混用。

3.3 调试范围与异常控制的字段

justMyCode是新手最容易踩坑的字段。默认true，意思是调试器只跟踪你自己写的代码，遇到库内部就当成黑盒。好处是单步时不会一头扎进 standard library 出不来。坏处是当你想看第三方库里到底发生了什么，断点会变成灰色的，根本停不下来。这时把它设为false，断点就能进库代码了。

logToFile可以把调试过程日志写到文件，排查调试器本身的问题时有用。console有三个值：integratedTerminal（集成终端，支持输入）、internalConsole（调试控制台，不支持 input）、externalTerminal（独立外部终端）。绝大多数情况选第一个。

4. 六类典型场景的调试配置实战

光看字段还是虚的，得放到具体场景里才有感觉。我把手头项目里最常见的六种启动方式整理出来，每一份配置都可以直接抄。

4.1 单文件脚本与带参数的脚本

最基础的就是 2.2 节那份。如果需要固定参数，改成这样：

{ "name": "Python: 带参数的脚本", "type": "debugpy", "request": "launch", "program": "${workspaceFolder}/scripts/etl.py", "args": ["--date", "2024-01-01", "--verbose"], "cwd": "${workspaceFolder}", "console": "integratedTerminal" }

这里有个细节：args传的值是字符串数组，不会做类型转换，所以你的 argparse 里该是 int 的还得自己转。调试时如果发现参数没生效，先检查是不是最后没按--隔开，或者args写成了字符串而不是数组。

4.2 以模块方式启动包项目

项目如果是标准包结构，src/下是代码，入口在src/app/main.py，直接用program指向那个文件会因为导入路径问题报错。这时候用module更稳妥：

{ "name": "Python: 模块启动", "type": "debugpy", "request": "launch", "module": "app.main", "cwd": "${workspaceFolder}/src", "env": { "PYTHONPATH": "${workspaceFolder}/src" }, "console": "integratedTerminal" }

PYTHONPATH那行是关键，它告诉 Python 去哪里找app这个包。如果你不确定要不要加，先不加跑一次，报 ModuleNotFoundError 再加上，这样能顺带搞清楚自己项目的导入到底是靠什么生效的。

4.3 调试测试用例

想调试某个失败的测试，不用写 print，直接让 pytest 停下来最省事。Python 扩展会为每个测试函数上方生成一个"调试测试"的按钮。如果你想在 launch.json 里手动配，用module模式启动 pytest：

{ "name": "Python: 调试 pytest", "type": "debugpy", "request": "launch", "module": "pytest", "args": ["-k", "test_login", "-x", "-s"], "cwd": "${workspaceFolder}", "console": "integratedTerminal" }

-k按名字筛选用例，-x遇到失败就停，-s让 print 正常输出。调试时在测试函数里打断点，就能精确停在逻辑出错那一步，比看 pytest 的断言堆栈直观太多。

4.4 Web 框架应用的调试配置

Django、Flask 这类应用有专门的字段，打开后调试器可以跳过框架内部的一堆初始化代码。以 Flask 为例：

{ "name": "Python: Flask", "type": "debugpy", "request": "launch", "module": "flask", "env": { "FLASK_APP": "app.py", "FLASK_DEBUG": "1" }, "args": ["run", "--no-reload"], "jinja": true, "justMyCode": false }

注意--no-reload很关键。Flask 默认的热重载会 fork 出子进程，调试器可能挂到父进程上导致断点失效。关掉重载，断点就稳了。jinja: true让调试器能进模板渲染逻辑，排查模板变量为空的 bug 时很管用。

4.5 附加到已运行的进程

排查常驻服务的问题时，重新启动会破坏现场，这时用 attach。先在目标进程启动时加上调试监听：

python -m debugpy --listen 5678 --wait-for-client app.py

然后配置 attach：

{ "name": "Python: 附加到进程", "type": "debugpy", "request": "attach", "connect": { "host": "127.0.0.1", "port": 5678 }, "pathMappings": [ { "localRoot": "${workspaceFolder}", "remoteRoot": "/app" } ] }

pathMappings是容器调试的重点：本地源码路径和容器内路径要一一对应映射，否则断点会标成"未绑定"。这个字段值写错，是容器调试最常见的"配了但断点不亮"的原因。

4.6 多进程与子进程调试

代码里用了multiprocessing或者调了外部脚本时，默认只有主进程能停断点。把subProcess打开：

{ "name": "Python: 调试子进程", "type": "debugpy", "request": "launch", "program": "${workspaceFolder}/main.py", "subProcess": true, "console": "integratedTerminal" }

不过要提醒一句，子进程之间共享调试端口有时会互相抢占，进程多了容易乱。我的经验是先把主进程逻辑调通，再单独为可疑的子进程写一份临时配置去跑，比一上来就全局追踪要清爽。

5. 把调试效率拉满的进阶技巧

配置能跑只是及格线，真正拉开差距的是断点的用法。这一节讲的几个技巧，学会了能让你的排查速度翻倍。

5.1 条件断点与日志断点

普通断点每次循环都停，一个一万次的 for 循环根本没法调。右键断点，选"编辑断点"，可以加条件表达式：比如i == 9999，只有满足时才停。这在排查"第一千条数据出错"这类问题时是救命的。

日志断点更巧，它不停程序，只是往控制台打一条消息，你可以写当前值: {value}, 索引: {i}。相当于不用改代码就能加 print，调完直接删断点，代码零污染。这个功能我用得最多，尤其是调试那些"加了 print 就复现不了"的诡异问题。

5.2 监视表达式与调用栈分析

程序停在断点时，左侧的变量面板能看到当前作用域所有变量。但有些值你需要计算才能得到，比如len(users)或order.price * order.qty，这时用"监视"面板，把表达式加进去，它会随单步实时更新。

调用栈面板是排查"谁调用了这个函数"的利器。当你停在一个深层函数里，调用栈会列出完整的调用链，点任意一帧就能切过去查看那一层的变量值。我曾经用一个空指针 bug 找了两小时，最后靠调用栈发现是上游传了个 None 进来，十秒定位。

5.3 justMyCode 与异常捕获

前面提过justMyCode默认true。当你确定 bug 出在第三方库，就把它设为false，然后进库代码打断点。反过来，如果你的断点全变灰了，先检查这个字段——多数"断点失效"其实是它把库代码排除掉了。

异常捕获方面，调试面板里可以勾选"遇到未捕获异常时暂停"。这样程序抛出异常的那一刻会立刻停下，而不是等到错误堆栈打印完才反应过来。排查那种"日志里只有一行 Traceback"的问题时非常好用。

5.4 用好调试控制台

调试控制台不只是看输出，你可以在程序暂停时，在里面直接输入 Python 表达式并回车执行。比如查看users[0].name，或者临时调用func(a, b)看看返回什么。它就像一个挂在当前断点现场的交互式解释器，所有变量都在手边。这个功能替代了大量"加一行 print 再重跑"的循环，用顺了很难再回去。

6. 常见问题速查与避坑

最后这一节把我这些年踩过的坑做个汇总，遇到问题可以直接对照排查。调试配不上的原因翻来覆去就那么几类，对着表找基本能定位。

6.1 断点变灰的三种典型情况

断点变灰是最常见的问题，但要分情况。如果是空心圆，说明这行代码根本没被执行到，可能是分支没进、函数没被调用，或者代码被注释掉了。如果断点带个黄色惊叹号，多半是源文件和实际运行的字节码对不上，常见于改了代码没保存、或者项目里有两份同名文件。还有一种是你想把断点下在虚拟环境的库文件里，但只要justMyCode是true，这些断点就永远停不下来。记住这三条，能省掉大量搜索时间。

6.2 解释器选错引发的连锁反应

解释器选错是隐藏最深的坑。现象是代码编辑器里不报错，但一调试就找不到模块。原因是 VSCode 的语言服务用了一个解释器，调试又用了另一个。排查方法很简单：调试启动后，看集成终端第一行打印的 Python 路径，对比你虚拟环境里的路径是否一致。不一致就回到命令面板重新选，选完重启调试。我现在的习惯是每个项目目录下都放一个.vscode/settings.json，把python.defaultInterpreterPath写死，团队协作时大家就不会互相踩。

6.3 多环境项目的配置组织方式

一个项目经常要跑开发、测试、生产几套环境，每套的数据库地址、日志级别都不同。与其改来改去，不如在 launch.json 里配多份 configuration，用不同name区分，调试时下拉框一选就行。公共部分可以放到settings.json或单独提取，但 launch.json 本身不支持配置继承，所以重复字段只能老实复制。为了减少维护成本，我更推荐把环境差异都塞进.env文件，然后配置里只保留envFile引用，这样 launch.json 保持干净，换环境只改 env 文件。

6.4 性能敏感场景的调试注意点

有些场景下调试器会明显拖慢程序，比如大数据量循环、网络请求密集的任务。这是正常的，因为每个断点判断和变量捕获都有开销。我的做法是：先在不设断点、只用日志断点的情况下跑一遍，缩小问题范围，再在可疑位置下少量条件断点。避免一上来就在热点循环里下普通断点，那样程序会慢到没法用。另外justMyCode: false会让调试器深入所有库调用，性能下降更明显，只在需要时临时开。

我用了这么多年，最深的一个体会是：调试配置这东西，配一次能受益一整个项目周期。花半小时把 launch.json 调顺手，比每次遇到问题都临时查资料要划算得多。建议你现在就拿手头正在写的项目练一遍，把单文件、模块启动、测试调试这三份配置先落地，后面遇到 Web 应用或者容器场景再逐个补。真到了线上问题复现的紧要关头，你会庆幸自己平时把这份配置打磨好了。