VS Code调试Docker环境下Django进程失败，寻求解决方案

我之前调试Docker里的Django时也踩过这个坑，给你几个实用的排查和解决方向，应该能帮你搞定：

1. 确认ptvsd在Django进程中的初始化配置 #

首先得保证你的manage.py（或自定义启动脚本）里的ptvsd配置是容器外部可访问的，别只绑定localhost（容器的localhost和宿主机不是同一个网络空间）。示例代码如下：

import ptvsd

# 关键：绑定0.0.0.0允许外部连接，端口选你约定的（比如5678）
ptvsd.enable_attach(address=('0.0.0.0', 5678))
# 可选：如果想让进程等待调试器连接后再启动，加上这行
ptvsd.wait_for_attach()

同时，docker-compose.yml必须把这个调试端口映射到宿主机：

services:
  web:
    build: .
    ports:
      - "8000:8000"  # Django服务端口
      - "5678:5678"  # 必须映射ptvsd调试端口
    command: python manage.py runserver 0.0.0.0:8000

2. 检查VS Code launch.json的路径映射 #

这是最容易踩坑的点！launch.json里的pathMappings必须保证本地项目路径和容器内项目路径完全对应，不然调试器找不到源码会直接崩溃。示例配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Docker: Attach to Django",
            "type": "python",
            "request": "attach",
            "port": 5678,
            "host": "localhost",
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",  # 本地项目根目录
                    "remoteRoot": "/app"  # 容器内你的Django项目根目录，要和Dockerfile的WORKDIR一致
                }
            ]
        }
    ]
}

一定要确认remoteRoot是容器里项目的绝对路径，比如你Dockerfile里写了WORKDIR /code，这里就要改成/code

3. 验证Docker环境的ptvsd安装 #

确保Docker容器里确实装了ptvsd 3.0.0，而且是在当前运行环境中（比如用虚拟环境的话，要装在虚拟环境里）。可以把ptvsd加到requirements.txt，或者在Dockerfile里直接安装：

FROM python:3.9

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt
# 直接指定版本安装，或者把ptvsd==3.0.0加到requirements.txt
RUN pip install ptvsd==3.0.0

COPY . .

如果用了虚拟环境，启动命令要确保激活虚拟环境后再运行Django，比如：

command: /app/venv/bin/python manage.py runserver 0.0.0.0:8000

4. 排查网络连通性问题 #

有时候宿主机防火墙会拦截调试端口，先在宿主机测试端口是否能连通：

# 用telnet测试
telnet localhost 5678
# 或者用nc（netcat）
nc -zv localhost 5678

如果连不通，先检查docker-compose up是否正常启动了容器（用docker ps看容器状态），再看容器日志有没有报错：

docker logs <你的容器名称>

5. 尝试升级到debugpy（ptvsd的替代方案） #

ptvsd 3.0.0是比较旧的版本了，现在官方已经把ptvsd改名为debugpy，兼容性更好。你可以试试替换：

• 容器内安装debugpy：pip install debugpy
• 修改manage.py的调试代码：

import debugpy

debugpy.listen(('0.0.0.0', 5678))
# 可选：等待调试器连接
debugpy.wait_for_client()

• launch.json的配置不需要大改，还是用type: python的attach配置即可。

6. 查看VS Code调试日志找具体原因 #

如果以上都没用，打开VS Code的调试日志看看详细错误：

1. 打开VS Code设置，搜索Python: Logging Level，改成Debug
2. 启动调试会话，然后打开View > Output，选择Python输出面板，里面会有调试器终止的具体原因，比如端口连接失败、路径映射错误等。

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