PyCharm调试Docker Compose启动的Django服务器时断点失效

以下是针对该问题的具体排查步骤和解决方案：

1. 确认调试端口映射与网络连通性 #

• 在docker-compose.yml中，确保调试端口（默认5678）已正确映射到主机：

  services:
    your-django-service:
      ports:
        - "8000:8000"
        - "5678:5678"  # 必须添加这一行
  

• 容器内的Pydevd需要连接到主机的正确IP：
  • Windows/macOS：直接使用host.docker.internal作为调试主机地址
  • Linux：在docker-compose.yml中添加extra_hosts: - "host.docker.internal:host-gateway"，然后使用该地址

2. 保证代码路径完全同步 #

• 检查docker-compose.yml的volumes配置，确保本地代码目录与容器内路径严格对应：

  volumes:
    - ./your-project-root:/app  # 本地项目根目录映射到容器内/app
  

• 确认PyCharm的项目根目录与本地映射目录一致，否则断点的本地文件路径和容器内代码路径不匹配，无法触发

3. 匹配Pydevd版本与启动配置 #

• 容器内必须安装与PyCharm版本对应的pydevd-pycharm包：

  # 对应PyCharm 2023.1.4的版本号
  pip install pydevd-pycharm~=231.9161.38
  

• 修改Django启动命令，添加调试参数：

  python -m pydevd-pycharm --host=host.docker.internal --port=5678 manage.py runserver 0.0.0.0:8000
  

  或者在manage.py开头手动插入调试初始化代码：

  import pydevd_pycharm
  pydevd_pycharm.settrace('host.docker.internal', port=5678, stdoutToServer=True, stderrToServer=True)
  

4. 检查PyCharm调试配置 #

• 在Run/Debug Configurations中选择Docker Compose配置：
  • 确认目标服务为你的Django服务，勾选Debug container选项
  • Python解释器选择Docker Compose对应的服务解释器，路径需与容器内Python路径一致（如/usr/local/bin/python）
  • 避免使用“Attach to process”模式，直接通过Docker Compose启动调试会话

5. 清理缓存与重建环境 #

• 清理PyCharm缓存：File -> Invalidate Caches... -> Invalidate and Restart
• 彻底重置Docker环境：

  docker-compose down -v  # 删除容器、卷和网络
  docker-compose build --no-cache  # 无缓存重新构建镜像
  docker-compose up -d
  

6. 防火墙与网络规则排查 #

• 主机防火墙需允许5678端口的入站连接，避免容器无法连接到PyCharm调试服务
• Linux系统下检查iptables规则，确保容器到主机的5678端口通信未被阻断

内容的提问来源于stack exchange，提问作者Prototype