用 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.jsonVSCode 会弹一个环境选择菜单让你选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 扩展面板里装两个东西Pythonms-python.python和Python Debuggerms-python.debugpy。前者提供语言服务、解释器选择、测试集成后者才是提供调试能力的核心。有些老教程还在提 ptvsd那已经是历史包袱了现在的调试后端统一是 debugpy装新扩展就行。装完扩展按CtrlShiftP打开命令面板输入Python: Select Interpreter选中你项目要用的解释器。如果你用了虚拟环境或者 conda这里一定要选到虚拟环境里的那个解释器而不是系统全局的。选错解释器最典型的症状是代码里明明装了 requests一调试就报 ModuleNotFoundError。2.2 生成第一份 launch.json打开一个 Python 文件点左侧活动栏的运行和调试图标或者按CtrlShiftD点击创建 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 调试工具栏与必背快捷键启动调试后顶部会浮出一排按钮继续、单步跳过、单步进入、单步跳出、重启、停止。它们对应的快捷键建议直接背下来用熟了效率提升非常明显快捷键功能使用时机F5启动 / 继续开始调试或从断点继续跑F9切换断点光标所在行加/删断点F10单步跳过不进入函数内部只看当前层F11单步进入进入被调用的函数内部ShiftF11单步跳出从当前函数返回到上一层ShiftF5停止调试结束整个会话CtrlShiftF5重启调试改完代码重新跑注意F10 和 F11 别搞反。想快速掠过一批不关心的库代码用 F10想钻进自己写的函数里查逻辑用 F11进去之后用 ShiftF11 出来。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.exeLinux/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. 常见问题速查与避坑最后这一节把我这些年踩过的坑做个汇总遇到问题可以直接对照排查。调试配不上的原因翻来覆去就那么几类对着表找基本能定位。现象最可能的原因处理方式断点是灰色空心圆代码未被执行到或 justMyCode 排除了库代码确认执行路径或把 justMyCode 设为 false断点是灰色带感叹号源文件与运行文件不一致改了没保存/版本不对保存文件确认运行的是当前代码ModuleNotFoundError解释器选错或 PYTHONPATH 未配置重新 Select Interpreter补 env 里的 PYTHONPATH调试时 input() 收不到输入console 设成了 internalConsole改为 integratedTerminalFlask/Django 断点失效热重载 fork 了子进程启动参数加 --no-reload容器内断点不亮pathMappings 没配或路径写错核对本地与容器内的绝对路径映射找不到 launch.json配置文件不在 .vscode 目录下移动到项目根目录的 .vscode 下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 应用或者容器场景再逐个补。真到了线上问题复现的紧要关头你会庆幸自己平时把这份配置打磨好了。
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.jsonVSCode 会弹一个环境选择菜单让你选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 扩展面板里装两个东西Pythonms-python.python和Python Debuggerms-python.debugpy。前者提供语言服务、解释器选择、测试集成后者才是提供调试能力的核心。有些老教程还在提 ptvsd那已经是历史包袱了现在的调试后端统一是 debugpy装新扩展就行。装完扩展按CtrlShiftP打开命令面板输入Python: Select Interpreter选中你项目要用的解释器。如果你用了虚拟环境或者 conda这里一定要选到虚拟环境里的那个解释器而不是系统全局的。选错解释器最典型的症状是代码里明明装了 requests一调试就报 ModuleNotFoundError。2.2 生成第一份 launch.json打开一个 Python 文件点左侧活动栏的运行和调试图标或者按CtrlShiftD点击创建 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 调试工具栏与必背快捷键启动调试后顶部会浮出一排按钮继续、单步跳过、单步进入、单步跳出、重启、停止。它们对应的快捷键建议直接背下来用熟了效率提升非常明显快捷键功能使用时机F5启动 / 继续开始调试或从断点继续跑F9切换断点光标所在行加/删断点F10单步跳过不进入函数内部只看当前层F11单步进入进入被调用的函数内部ShiftF11单步跳出从当前函数返回到上一层ShiftF5停止调试结束整个会话CtrlShiftF5重启调试改完代码重新跑注意F10 和 F11 别搞反。想快速掠过一批不关心的库代码用 F10想钻进自己写的函数里查逻辑用 F11进去之后用 ShiftF11 出来。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.exeLinux/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. 常见问题速查与避坑最后这一节把我这些年踩过的坑做个汇总遇到问题可以直接对照排查。调试配不上的原因翻来覆去就那么几类对着表找基本能定位。现象最可能的原因处理方式断点是灰色空心圆代码未被执行到或 justMyCode 排除了库代码确认执行路径或把 justMyCode 设为 false断点是灰色带感叹号源文件与运行文件不一致改了没保存/版本不对保存文件确认运行的是当前代码ModuleNotFoundError解释器选错或 PYTHONPATH 未配置重新 Select Interpreter补 env 里的 PYTHONPATH调试时 input() 收不到输入console 设成了 internalConsole改为 integratedTerminalFlask/Django 断点失效热重载 fork 了子进程启动参数加 --no-reload容器内断点不亮pathMappings 没配或路径写错核对本地与容器内的绝对路径映射找不到 launch.json配置文件不在 .vscode 目录下移动到项目根目录的 .vscode 下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 应用或者容器场景再逐个补。真到了线上问题复现的紧要关头你会庆幸自己平时把这份配置打磨好了。
 空间优化)
