如何将Django应用Docker化并通过VSCode调试？含docker-compose示例

一、可行性说明 #

完全可以实现。借助VSCode的Python远程调试功能，配合Docker容器的端口映射与调试器配置，即使是用docker-compose管理Django、PostgreSQL、Redis多服务的场景，也能顺利进行断点调试。

二、具体操作步骤 #

1. 配置Docker与docker-compose #

（1）Dockerfile添加调试依赖

在Django应用的Dockerfile中安装debugpy（Python官方调试器）：

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install debugpy  # 安装调试工具

COPY . .

（2）docker-compose.yml配置服务

修改docker-compose.yml，给Django服务添加调试端口映射，并调整启动命令以启动调试监听：

version: '3.8'

services:
  web:
    build: .
    # 启动debugpy监听所有地址的5678端口，同时启动Django服务
    command: python -m debugpy --listen 0.0.0.0:5678 manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app  # 挂载本地代码到容器，确保修改实时同步
    ports:
      - "8000:8000"  # 应用端口
      - "5678:5678"  # 调试端口映射到本地
    depends_on:
      - db
      - redis
    environment:
      - DEBUG=1
      - DATABASE_URL=postgres://user:password@db:5432/mydb
      - REDIS_URL=redis://redis:6379/0

  db:
    image: postgres:14-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=mydb

  redis:
    image: redis:alpine
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

2. 配置VSCode调试文件 #

在项目根目录的.vscode文件夹下创建launch.json，添加远程调试配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Docker: Django Remote Debug",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            // 映射本地代码目录与容器内代码目录，确保断点匹配
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "/app"
                }
            ],
            "justMyCode": false  // 允许调试第三方库代码（可选）
        }
    ]
}

3. 启动调试流程 #

• 运行命令启动所有服务：docker-compose up --build
• 在VSCode中给Django代码设置断点（点击代码行号左侧的空白区域）
• 打开VSCode调试面板，选择Docker: Django Remote Debug配置，点击绿色启动按钮
• 访问http://localhost:8000触发业务逻辑，当代码执行到断点时，VSCode会自动暂停，此时可以查看变量、单步执行、调用栈等调试操作

三、关键注意事项 #

• 确保pathMappings中的remoteRoot与Docker容器内的工作目录完全一致，否则VSCode无法正确关联本地与容器内的代码
• 容器内的Python版本尽量与本地VSCode使用的Python版本保持一致，避免调试兼容性问题
• 启动命令中的--listen 0.0.0.0:5678不能改为localhost:5678，否则本地无法连接容器内的调试端口

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