📖 目录

  1. 快速开始
  2. 基础调试
  3. 高级配置
  4. 框架调试
  5. 远程调试
  6. 实用技巧
  7. 故障排除

🚀 快速开始

安装准备

# 必需扩展
- Python (Microsoft官方扩展)
- Python Debugger (推荐)

最简调试流程

  1. 设置断点：点击行号左侧
  2. 启动调试：按 F5
  3. 选择配置：选择 "Python File"

🔧 基础调试

调试控制面板

按钮快捷键功能
▶️ 继续F5执行到下一个断点
⏸️ 暂停Ctrl+F5暂停执行
⏭️ 单步跳过F10执行当前行
↓ 单步进入F11进入函数内部
↑ 单步跳出Shift+F11跳出当前函数
🔄 重启Ctrl+Shift+F5重新开始
⏹️ 停止Shift+F5停止调试

调试视图区域

  • 变量 (Variables)：查看和修改变量值
  • 监视 (Watch)：添加自定义表达式监控
  • 调用堆栈 (Call Stack)：查看函数调用链
  • 断点 (Breakpoints)：管理所有断点

⚙️ 高级配置

launch.json 核心配置

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

常用配置模板

1. 带参数调试

{
    "args": ["--input", "data.csv", "--verbose"]
}

2. 模块调试

{
    "module": "pytest",
    "args": ["tests/", "-v"]
}

🏗️ 框架调试

Django 项目调试

{
    "name": "Python: Django",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/manage.py",
    "args": ["runserver", "--noreload"],
    "django": true,
    "autoStartBrowser": false
}

Flask 应用调试

{
    "name": "Python: Flask",
    "type": "debugpy",
    "request": "launch",
    "module": "flask",
    "env": {
        "FLASK_APP": "app.py",
        "FLASK_DEBUG": "1"
    },
    "args": ["run", "--port", "5000"]
}

测试框架调试

{
    "name": "Python: Pytest",
    "type": "debugpy",
    "request": "launch",
    "module": "pytest",
    "args": ["${file}", "-v", "-s", "--tb=short"]
}

🌐 远程调试

配置示例

{
    "name": "Python: 远程附加",
    "type": "debugpy",
    "request": "attach",
    "connect": {
        "host": "localhost",
        "port": 5678
    },
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/remote/path"
        }
    ]
}

远程代码启动

import debugpy
debugpy.listen(5678)
debugpy.wait_for_client()  # 等待调试器连接
# 你的代码从这里开始执行

🎯 实用技巧

1. 智能断点

  • 条件断点：右键断点 → 设置条件
  • 日志点：输出信息而不暂停执行
  • 函数断点：在函数调用时暂停

2. 调试控制台

  • 在调试过程中执行任意 Python 代码
  • 修改变量值实时生效
  • 导入模块测试函数

3. 性能分析

{
    "cProfile": {
        "enable": true,
        "output": "${workspaceFolder}/profile.prof"
    }
}

4. 多进程调试

{
    "subProcess": true,  // 调试子进程
    "multiprocess": true  // 支持多进程
}

🔍 调试技巧进阶

1. 条件断点高级用法

# 仅当条件满足时暂停
# 例如：列表长度大于10时暂停
if len(items) > 10:  # 在此行设置条件断点
    process_items(items)

2. 监视表达式

# 在Watch面板添加：
- len(data_list)
- user.name if user else None
- [x for x in items if x.active]
- f"总数: {count}, 平均: {total/count:.2f}"

3. 异常断点

  1. 打开断点视图
  2. 点击 "+" 添加异常断点
  3. 选择异常类型（如：所有异常、特定异常）

🐛 常见问题解决

问题1：调试无法启动

解决方案：

{
    "python": "/usr/bin/python3",  // 指定解释器路径
    "cwd": "${workspaceFolder}"     // 设置工作目录
}

问题2：断点不生效

检查点：

  1. 确保文件已保存
  2. 检查 justMyCode 设置
  3. 验证文件路径是否正确

问题3：导入错误

{
    "env": {
        "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}/lib"
    }
}

🎨 自定义调试体验

1. 颜色主题定制

{
    "workbench.colorCustomizations": {
        "debugToolBar.background": "#1e1e1e",
        "debugIcon.startForeground": "#00ff00"
    }
}

2. 快捷键自定义

{
    "keybindings": [
        {
            "key": "ctrl+shift+d",
            "command": "workbench.action.debug.start"
        }
    ]
}

3. 复合调试配置

{
    "compounds": [
        {
            "name": "全栈调试",
            "configurations": ["后端API", "前端服务", "数据库"],
            "stopAll": true
        }
    ]
}

📊 调试最佳实践

1. 分层调试策略

  • 开发阶段：启用 justMyCode: false，深入第三方库
  • 测试阶段：使用条件断点和日志点
  • 生产调试：仅启用关键断点，记录调试日志

2. 性能优化建议

{
    "skipFiles": [
        "<node_internals>/**",
        "**/site-packages/**/*.py"
    ]
}

3. 团队协作配置

# 将 launch.json 提交到版本控制
# 确保团队成员配置一致
# 使用环境变量替代硬编码配置

🚀 高效调试工作流

日常调试流程

  1. 准备阶段

    • 设置关键断点
    • 添加监视表达式
    • 配置环境变量

  2. 执行阶段

    • 启动调试
    • 逐步执行代码
    • 观察变量变化

  3. 分析阶段

    • 检查调用堆栈
    • 查看异常信息
    • 修改代码并重新测试

快捷键速查表

操作快捷键
开始调试F5
切换断点F9
单步进入F11
单步跳过F10
重启调试Ctrl+Shift+F5
停止调试Shift+F5
打开调试控制台Ctrl+Shift+Y
查看所有断点Ctrl+Shift+F8

💡 高级调试场景

异步代码调试

{
    "name": "Python: Async",
    "type": "debugpy",
    "request": "launch",
    "program": "${file}",
    "asyncio": true,  // 支持异步
    "gevent": true    // 支持协程
}

Jupyter Notebook 调试

  1. 安装 Jupyter 扩展
  2. 在单元格左侧设置断点
  3. 使用专用调试按钮启动

容器内调试

{
    "dockerOptions": {
        "image": "python:3.9",
        "volumes": ["${workspaceFolder}:/workspace"],
        "workspaceMount": "/workspace"
    }
}

📝 总结

VS Code Python 调试提供了：

  • ✅ 直观的界面：图形化调试控制
  • ✅ 强大的功能：条件断点、远程调试、多进程支持
  • ✅ 灵活的配置：JSON 配置满足各种需求
  • ✅ 丰富的扩展：支持主流框架和工具

核心建议：

  1. 从简单配置开始，逐步增加复杂度
  2. 合理使用条件断点和监视表达式
  3. 为不同场景创建专用调试配置
  4. 定期更新调试配置以适应项目变化

通过掌握这些调试技巧，你将能够：

  • 🎯 快速定位和修复 bug
  • ⚡ 提高开发效率
  • 🔧 深入理解代码执行流程
  • 🚀 加速项目开发进程

立即尝试：

# 测试代码
def debug_demo():
    data = [1, 2, 3, 4, 5]
    total = 0
    for item in data:
        total += item  # 在此设置断点
        print(f"当前累计: {total}")
    return total

if __name__ == "__main__":
    result = debug_demo()
    print(f"最终结果: {result}")