如何在Visual Studio Code中调试Docker化的Django项目？

方案一：修复VS Code本地调试的preLaunchTask错误 #

1. 排查任务失败根源

   • 先手动在终端执行docker-compose -f docker-compose.dev.yml up，确认服务能否正常启动。如果有报错（比如数据库连接失败、依赖包缺失），先解决这些基础问题，确保服务可以稳定运行。
   • 检查.vscode/tasks.json配置，确保命令正确指定了dev配置文件，示例配置：

     {
         "version": "2.0.0",
         "tasks": [
             {
                 "label": "docker-compose up",
                 "type": "shell",
                 "command": "docker-compose -f docker-compose.dev.yml up",
                 "args": [],
                 "isBackground": true,
                 "problemMatcher": {
                     "pattern": {
                         "regexp": "^.*$"
                     },
                     "background": {
                         "activeOnStart": true,
                         "beginsPattern": "^.*Starting.*$",
                         "endsPattern": "^.*started.*$"
                     }
                 }
             }
         ]
     }
     

   • 注意isBackground和problemMatcher的配置，避免VS Code误判任务未完成而终止。

2. 匹配launch.json调试配置
   确保launch.json中调试目标与容器配置一致，示例attach配置：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Django Docker Debug",
               "type": "python",
               "request": "attach",
               "connect": {
                   "host": "localhost",
                   "port": 5678
               },
               "pathMappings": [
                   {
                       "localRoot": "${workspaceFolder}",
                       "remoteRoot": "/app" // *替换为容器内Django项目的实际路径*
                   }
               ]
           }
       ]
   }
   

   同时要在docker-compose.dev.yml中把调试端口5678映射到本地。

方案二：直接附加到已运行的Django容器调试 #

跳过preLaunchTask环节，直接调试已启动的容器，步骤更简洁：

1. 给容器安装debugpy

   • 方式一：修改项目Dockerfile，添加RUN pip install debugpy，然后重新构建镜像：docker-compose -f docker-compose.dev.yml build django
   • 方式二：直接进入运行中的容器安装：docker exec -it <你的Django容器名> pip install debugpy

2. 修改启动命令开启调试模式

   • 在docker-compose.dev.yml中，将django服务的command修改为：

     command: python -m debugpy --listen 0.0.0.0:5678 manage.py runserver 0.0.0.0:8000
     

   • 添加端口映射规则：

     ports:
       - "8000:8000"
       - "5678:5678"
     

   • 重启容器：docker-compose -f docker-compose.dev.yml restart django

3. 启动VS Code调试
   使用方案一中的launch.json配置，点击F5即可附加到容器，此时可以正常设置断点调试代码。

方案三：修复Dev Containers的Workspace问题 #

1. 确认容器路径映射
   检查docker-compose.dev.yml中本地项目目录是否正确映射到容器内路径，示例：

   volumes:
     - .:/app # 本地当前目录映射到容器内的/app路径
   

2. 配置devcontainer.json
   在.vscode目录下创建devcontainer.json，指定正确的工作区路径：

   {
       "name": "Django Dev Env",
       "dockerComposeFile": "docker-compose.dev.yml",
       "service": "django", // 对应docker-compose中的服务名
       "workspaceFolder": "/app", // 和volume映射的容器路径完全一致
       "extensions": [
           "ms-python.python",
           "ms-python.debugpy"
       ]
   }
   

3. 重新加载容器
   先停止当前运行的容器：docker-compose -f docker-compose.dev.yml down，然后在VS Code中执行“Open folder in container”，此时应该能正常加载容器并进入工作区。

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