VSCode中Docker Compose多Python容器远程调试配置异常

问题根源 #

报错是因为多个调试配置共享了错误的路径映射规则，调试Celery Worker 2时，VSCode套用了Celery Worker 1的路径映射，导致无法匹配容器内的代码路径。

解决步骤 #

1. 为每个容器配置独立的DebugPy监听端口 #

每个Python服务容器需要启动DebugPy并监听专属端口，避免端口冲突，同时在Docker Compose中完成端口映射。

Docker Compose配置示例

services:
  flask:
    build: ./flask
    ports:
      - "5000:5000"
      - "5678:5678"  # DebugPy映射端口
    command: python -m debugpy --listen 0.0.0.0:5678 --wait-for-client app.py

  celeryWorker1:
    build: ./celeryWorker1
    ports:
      - "5679:5679"  # DebugPy映射端口
    command: python -m debugpy --listen 0.0.0.0:5679 --wait-for-client -m celery -A worker.tasks worker --loglevel=info

  celeryWorker2:
    build: ./celeryWorker2
    ports:
      - "5680:5680"  # DebugPy映射端口
    command: python -m debugpy --listen 0.0.0.0:5680 --wait-for-client -m celery -A worker.tasks worker --loglevel=info

注意事项

• 每个容器的--listen端口要与ports字段的主机映射端口严格对应
• --wait-for-client会让服务暂停直到调试器连接，适合调试启动流程；不需要可直接移除
• 确保容器的Dockerfile中已安装DebugPy：RUN pip install debugpy

2. 配置VSCode launch.json，为每个容器单独设置路径映射 #

在.vscode/launch.json中为每个服务创建独立的调试配置，明确指定对应端口和路径映射规则，避免配置混淆。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Flask",
      "type": "python",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}/flask/app",
          "remoteRoot": "/path/to/flask/app"
        }
      ],
      "justMyCode": false
    },
    {
      "name": "Attach to Celery Worker 1",
      "type": "python",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5679
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}/celeryWorker1/app",
          "remoteRoot": "/path/to/celeryworker1/app"
        }
      ],
      "justMyCode": false
    },
    {
      "name": "Attach to Celery Worker 2",
      "type": "python",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5680
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}/celeryWorker2/app",
          "remoteRoot": "/path/to/celeryworker2/app"
        }
      ],
      "justMyCode": false
    }
  ],
  "compounds": [
    {
      "name": "Attach to All Services",
      "configurations": ["Attach to Flask", "Attach to Celery Worker 1", "Attach to Celery Worker 2"]
    }
  ]
}

关键配置说明

• pathMappings: 必须保证remoteRoot与容器内代码的实际绝对路径完全一致（注意大小写，需匹配报错中的路径格式）
• port: 对应Docker Compose中映射到主机的DebugPy端口
• compounds: 可选配置，支持一键启动所有三个调试会话

3. 验证调试流程 #

1. 启动Docker Compose栈：docker-compose up --build
2. 在VSCode的运行和调试面板：
   • 单独调试某服务：选择对应配置点击启动
   • 同时调试所有服务：选择Attach to All Services点击启动

常见排查点 #

• 检查容器内代码路径是否与remoteRoot一致：进入容器执行pwd确认
• 确保DebugPy已正确安装：进入容器执行pip list | grep debugpy
• 检查端口是否被占用：主机执行lsof -i :<端口号>确认

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