调试大型Python项目需建立可复现、可追踪、可协作的体系：用logging分级替代print，善用breakpoint()和pdb，预置tracemalloc/py-spy等诊断工具，并提供含复现步骤、日志、环境、排查记录的完整调试摘要。
调试大型 Python 项目，核心不是靠 print 或反复运行，而是建立一套可复现、可追踪、可协作的调试习惯和工具链。
用 logging 替代 print，且分级控制输出
print 在大型项目中很快失控：不知道谁打的、在哪打的、该不该留、上线要不要删。logging 提供层级（DEBUG/INFO/WARNING/ERROR）、来源（模块名、行号）、格式化和动态开关能力。
建议做法：
- 项目启动时统一配置 root logger，输出到文件 + 控制台，级别设为 INFO；调试时临时设为 DEBUG
- 每个模块用
logger = logging.getLogger(__name__)获取独立 logger，避免全局污染 - 敏感信息（如密码、token）绝不打日志；必要时用
logger.debug("user_id=%s", user_id)延迟格式化，避免误触发 - 在关键路径（如函数入口、RPC 响应前、DB 提交后）加结构化日志，例如：
logger.info("task_finished", extra={"task_id": tid, "duration_ms": elapsed})
善用断点调试器，但别只依赖 IDE 图形界面
PyCharm / VS Code 的图形断点很直观，但在服务器、CI 环境或多人协作排查时，往往只能靠命令行。掌握 pdb 和 breakpoint() 是基本功。
立即学习“Python免费学习笔记（深入）”；
实用技巧：
- Python 3.7+ 直接写
breakpoint()，会自动调用当前 $PYTHONBREAKPOINT 设置（默认 pdb），比import pdb; pdb.set_trace()更简洁 - 远程调试时，在目标进程启动前加环境变量：
PYTHONBREAKPOINT=remote_pdb.set_trace（需装 remote-pdb），然后 telnet localhost:4444 连入 - 在循环里慎用普通断点——改用条件断点（IDE 中右键断点设 condition）或
if i == 123: breakpoint() - 进入 pdb 后，常用命令：
n下一行、s进入函数、pp var_name美观打印变量、!var = new_value临时修改、q退出
针对常见问题类型，预置诊断手段
大型项目出问题有规律可循。不必每次从零分析，提前准备“检查清单”和辅助脚本能大幅提速。
典型场景应对：
-
内存持续增长：用
tracemalloc定位源头。启动时加tracemalloc.start(25)，出问题后调用snapshot = tracemalloc.take_snapshot()，再用snapshot.statistics('lineno')查分配最多的位置 -
CPU 占用高：先用
top -H -p $(pgrep -f your_script.py)找高负载线程 PID，再用py-spy record -p PID -o profile.svg（需装 py-spy）生成火焰图 -
异步/多线程死锁或卡顿：启用
threading.settrace()或用asyncio.get_event_loop().set_debug(True)捕获慢回调和未 await 的协程 -
依赖版本冲突：运行
pipdeptree --warn stale检查过期包，用pip check验证依赖兼容性
让调试信息“自带上下文”，减少重复提问
当把问题抛给同事或写进 issue 时，有效信息决定响应速度。不要只说“接口超时”，而要提供可复现的最小线索。
一份合格的调试摘要应包含：
- 完整复现步骤（含输入参数、时间、环境标识，如
curl -X POST ... -d '{"user_id": 1001}'） - 相关日志片段（带时间戳和 trace_id，不截首尾，保留堆栈全貌）
- 执行环境快照：
python --version、pip list | grep -E "(your-package|django|fastapi)"、部署方式（Docker？K8s？进程数？） - 已尝试的排查动作及结果（例如：“加了 logging 输出，发现 DB 查询耗时 8s；执行 EXPLAIN 分析，命中索引失效”）
