Docker-Compose配置下VSCode调试Python FastAPI应用失败求助

核心调整方向 #

添加MariaDB后，需要解决两个核心问题：一是确保应用启动前数据库已就绪，二是配置VSCode用Attach模式正确连接容器内的debugpy。

1. 优化Dockerfile：处理依赖等待与调试启动 #

修改Dockerfile，加入数据库等待逻辑并保留debugpy配置：

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install debugpy

# 安装netcat用来检测数据库端口（替代wait-for-it脚本）
RUN apt-get update && apt-get install -y --no-install-recommends netcat-traditional && rm -rf /var/lib/apt/lists/*

COPY . .

# 自定义等待数据库脚本，启动前检测db服务的3306端口
CMD ["sh", "-c", "while ! nc -z db 3306; do sleep 1; done; python -m debugpy --listen 0.0.0.0:5678 --wait-for-client -m uvicorn main:app --host 0.0.0.0 --port 8000"]

2. 配置docker-compose.debug.yml：关联服务与端口 #

确保数据库服务定义正确，调试容器依赖数据库并暴露调试端口：

version: '3.8'
services:
  web:
    build: .
    ports:
      - "8000:8000"
      - "5678:5678"  # 必须暴露debugpy监听的端口
    environment:
      # 数据库连接用服务名"db"，不是localhost
      DATABASE_URL: "mysql+pymysql://fastapi_user:fastapi_pass@db:3306/fastapi_db"
    depends_on:
      - db
    volumes:
      - .:/app  # 挂载本地代码，实时同步修改
  db:
    image: mariadb:10.11
    environment:
      MYSQL_ROOT_PASSWORD: root_pass
      MYSQL_DATABASE: fastapi_db
      MYSQL_USER: fastapi_user
      MYSQL_PASSWORD: fastapi_pass
    ports:
      - "3306:3306"
    volumes:
      - mariadb_data:/var/lib/mysql

volumes:
  mariadb_data:

3. 重写launch.json：切换到Attach模式 #

放弃原来的Launch模式，改用Attach连接容器内的debugpy：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to FastAPI Container",
      "type": "python",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "/app"
        }
      ],
      "justMyCode": true
    }
  ]
}

4. 调整tasks.json：先启动容器服务 #

配置任务先启动所有依赖服务，再触发调试：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start Debug Containers",
      "type": "docker-compose",
      "dockerCompose": {
        "up": {
          "detached": true,
          "build": true,
          "services": ["web", "db"]
        },
        "files": ["${workspaceFolder}/docker-compose.debug.yml"]
      },
      "problemMatcher": [],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

调试操作步骤 #

1. 运行Start Debug Containers任务，等待容器启动（此时web容器会卡在--wait-for-client状态，等待调试连接）
2. 启动Attach to FastAPI Container调试会话，VSCode会自动连接到容器的5678端口，应用开始运行

关键注意点 #

• 数据库连接字符串的主机名必须是docker-compose中MariaDB的服务名（如db），容器内部通过服务名互相访问
• 确保本地代码挂载到容器，否则调试时修改的代码不会同步到容器内
• 如果不用netcat，也可以用wait-for-it脚本，逻辑一致，都是等待数据库就绪后再启动应用

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