2. 调试环境搭建

调试环境搭建，说白了就是给你的代码装上「监控探头」和「黑匣子」。

我见过太多项目重构到一半，发现日志打不出来、断点挂不上去、远程连不上——整个团队卡在那干瞪眼。嗯，今天我们就把这几个坑填平。

一、IDE调试器配置：VS Code 与 PyCharm

IDE调试器是日常调试的主力。我个人习惯两个都装，但主力用VS Code——轻量、快、插件生态好。PyCharm呢，适合大型项目，尤其是Django或数据科学场景。

VS Code 调试配置

VS Code的调试配置写在 .vscode/launch.json 里。我建议你直接点左侧「运行和调试」图标，然后创建 launch.json。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": false
        },
        {
            "name": "Python: Flask 调试",
            "type": "python",
            "request": "launch",
            "module": "flask",
            "env": {
                "FLASK_APP": "app.py",
                "FLASK_ENV": "development"
            },
            "args": [
                "run",
                "--no-debugger",
                "--no-reload"
            ],
            "justMyCode": false
        }
    ]
}
我的小技巧： 把 justMyCode 设为 false，这样能进入第三方库内部调试。有一次我排查一个requests库的bug，就是靠这个设置找到的。

PyCharm 调试配置

PyCharm的配置更图形化。你点右上角的「Add Configuration」，选Python，然后设置Script path和Parameters就行。

我个人觉得PyCharm最香的是「条件断点」——右键断点，输入条件表达式。比如我只想在 user_id == 10086 时停下来，就不用一次次按F9了。

注意： PyCharm的远程调试需要配置SSH解释器。我曾经因为密钥权限问题折腾了半小时，最后发现是 .ssh/config 里少写了个 IdentityFile。

二、日志框架配置：Loguru vs Logging

日志是调试的「黑匣子」。Python自带的 logging 模块够用，但配置起来啰嗦。我个人更推荐 Loguru——简洁、漂亮、开箱即用。

Loguru 配置

from loguru import logger

# 移除默认处理器
logger.remove()

# 添加控制台输出
logger.add(
    sys.stdout,
    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
    level="DEBUG"
)

# 添加文件输出，自动轮转
logger.add(
    "logs/app_{time:YYYY-MM-DD}.log",
    rotation="500 MB",
    retention="30 days",
    compression="zip",
    level="INFO"
)

为什么我选Loguru？

  • 一行代码搞定彩色输出
  • 自动轮转、压缩、清理
  • 异常追踪自带堆栈信息

Logging 配置（标准做法）

import logging
import logging.handlers

logger = logging.getLogger("my_app")
logger.setLevel(logging.DEBUG)

# 控制台处理器
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.DEBUG)
console_format = logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
console_handler.setFormatter(console_format)

# 文件处理器，按时间轮转
file_handler = logging.handlers.TimedRotatingFileHandler(
    'logs/app.log', when='midnight', backupCount=30
)
file_handler.setLevel(logging.INFO)
file_format = logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s'
)
file_handler.setFormatter(file_format)

logger.addHandler(console_handler)
logger.addHandler(file_handler)
避坑指南： 我曾经在项目重构时，把 logger 定义在多个模块里，结果日志重复打印。后来统一用 getLogger(__name__) 才解决。记住：每个模块用 __name__ 作为logger名。

三、远程调试设置

远程调试，说白了就是本地IDE连上远程服务器上的Python进程。我一般在两种场景用：一是服务器上跑着服务不能停，二是Docker容器里不好装IDE。

VS Code 远程调试

VS Code的Remote Development插件是神器。装好 Remote-SSH 插件，连上服务器，就能像本地一样调试。

# 在远程服务器上安装 debugpy
pip install debugpy

# 启动远程调试
python -m debugpy --listen 0.0.0.0:5678 --wait-for-client your_script.py

然后在本地VS Code的 launch.json 里加一个远程配置：

{
    "name": "Python: 远程调试",
    "type": "python",
    "request": "attach",
    "connect": {
        "host": "your-server-ip",
        "port": 5678
    },
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/path/to/remote/project"
        }
    ]
}
我的经验： pathMappings 一定要配对。有一次我本地路径是 /Users/me/project，远程是 /home/ubuntu/project，没映射对，断点根本停不下来。

PyCharm 远程调试

PyCharm的远程调试通过SSH解释器实现。配置路径：File → Settings → Project → Python Interpreter → 齿轮图标 → Add → SSH Interpreter。

配置好后，PyCharm会自动同步代码到远程服务器。你本地打断点，远程执行时就会停住。嗯，这个功能在调试Django或FastAPI时特别爽。

四、Docker环境下的调试

Docker调试比普通远程调试多一层容器隔离。我常用的方案有两种：

方案一：容器内安装 debugpy

# Dockerfile 中添加
RUN pip install debugpy

# 启动命令改为
CMD ["python", "-m", "debugpy", "--listen", "0.0.0.0:5678", "--wait-for-client", "app.py"]

然后 docker run 时映射端口：

docker run -p 5678:5678 your-image

方案二：使用 VS Code Dev Containers

这个更优雅。装好 Dev Containers 插件，在项目根目录创建 .devcontainer/devcontainer.json：

{
    "name": "Python 3.11",
    "image": "mcr.microsoft.com/devcontainers/python:3.11",
    "features": {},
    "forwardPorts": [5678],
    "postCreateCommand": "pip install -r requirements.txt",
    "customizations": {
        "vscode": {
            "extensions": ["ms-python.python"]
        }
    }
}

然后点左下角绿色图标 → Reopen in Container。VS Code会自动构建容器，你就能像本地一样调试了。

注意： Docker调试时，文件路径映射容易出问题。我建议在 launch.json 里明确写 pathMappings，把容器内路径映射到本地。

知识体系总览

下面这张图是我自己整理的调试环境搭建知识体系，你一看就明白各模块之间的关系：

调试环境搭建 IDE调试器配置 VS Code: launch.json PyCharm: SSH解释器 条件断点、路径映射 日志框架配置 Loguru: 简洁优雅 Logging: 标准灵活 轮转、压缩、格式化 远程调试设置 debugpy 监听 SSH 隧道转发 路径映射 Docker调试 容器内 debugpy Dev Containers 端口映射 目标：本地IDE → 远程服务器 → Docker容器，全链路可调试

这张图把调试环境分成四个模块：IDE配置是基础，日志框架是辅助，远程调试和Docker调试是进阶。你按这个顺序搭建，基本不会漏东西。

总结一下我的建议：

  • 日常开发：VS Code + Loguru，轻量高效
  • 大型项目：PyCharm + Logging，功能全面
  • 远程场景：debugpy + SSH，稳定可靠
  • 容器场景：Dev Containers，体验最好

调试环境搭好了，后面的事就顺了。你想想看，断点能打、日志能看、远程能连——还有什么bug是搞不定的？

可可精品资料库

← 上一章 📖 返回目录 下一章 →