VS code docker远程调试

在 VS Code 里对 Docker 容器中的 Python 做单步调试最常用两种方式直接附加到运行容器简单快速、远程 attach 调试灵活可控一、准备工作必做安装 VS Code 扩展Python微软官方Docker微软官方Dev Containers可选用于直接进入容器开发项目结构示例plaintextyour-project/ ├── app.py # 你的 Python 代码 ├── Dockerfile ├── requirements.txt └── .vscode/ ├── launch.json # 调试配置 └── tasks.json # 构建/运行任务可选二、方式一直接附加到运行容器推荐新手1. 编写 DockerfiledockerfileFROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 安装 debugpy调试必备 RUN pip install debugpy COPY . . # 启动命令用 debugpy 监听 0.0.0.0:5678等待客户端连接 CMD [python, -m, debugpy, --listen, 0.0.0.0:5678, --wait-for-client, app.py]2. 构建并运行容器暴露调试端口bash运行# 构建镜像 docker build -t my-python-app . # 运行容器映射调试端口 5678 docker run -d -p 5678:5678 --name my-python-container my-python-app3. VS Code 附加调试打开你的项目左侧「运行和调试」CtrlShiftD→ 「创建 launch.json 文件」选择Python → Remote Attach修改.vscode/launch.jsonjson{ version: 0.2.0, configurations: [ { name: Python: Attach to Docker, type: debugpy, request: attach, connect: { host: localhost, port: 5678 }, pathMappings: [ { localRoot: ${workspaceFolder}, remoteRoot: /app } ], justMyCode: false } ] }在app.py打断点选择配置「Python: Attach to Docker」→ 按F5启动调试即可单步调试F10 单步跳过、F11 单步进入、F5 继续三、方式二用 Dev Containers 直接在容器内开发最顺滑1. 一键生成 Docker 配置CtrlShiftP → 输入Dev Containers: Add Development Container Configuration Files...选择Python 3→ 选择版本 → 生成.devcontainer/配置2. 重新在容器中打开项目CtrlShiftP →Dev Containers: Reopen in ContainerVS Code 会自动构建镜像、启动容器并在容器内打开项目3. 直接调试和本地一样在容器内的 VS Code 窗口中直接打断点按F5→ 选择Python File即可单步调试无需额外端口映射四、方式三docker-compose 调试适合多服务1. docker-compose.ymlyamlversion: 3 services: app: build: . ports: - 5678:5678 # 调试端口 volumes: - .:/app # 本地代码映射到容器热更新 command: python -m debugpy --listen 0.0.0.0:5678 --wait-for-client app.py2. 启动bash运行docker-compose up -d3. 调试同方式一用launch.json附加到localhost:5678五、关键配置说明debugpyVS Code Python 调试的官方后端必须安装--listen 0.0.0.0:5678容器内监听所有网卡允许外部连接--wait-for-client程序启动后暂停直到 VS Code 附加成功pathMappings必须正确否则断点不生效localRoot本地项目路径${workspaceFolder}remoteRoot容器内代码路径如/app六、常见问题断点不命中检查pathMappings是否匹配确保容器内安装了debugpy重启容器与 VS Code连接超时检查端口映射5678:5678是否正确防火墙是否放行 5678 端口容器是否正常运行docker ps代码修改不生效用volumes映射本地代码到容器或在容器内重新安装依赖七、单步调试快捷键F5继续运行F10单步跳过不进入函数F11单步进入进入函数ShiftF11单步跳出CtrlShiftF5重启调试ShiftF5停止调试参考一这个命令的执行位置分两种核心场景我会用新手能直接看懂的方式讲清楚还会补充关键注意事项一、核心执行位置两种方式方式 1作为容器启动命令推荐无需手动进容器这是最常用的方式你不需要手动登录容器执行而是把这个命令写在 Dockerfile/docker-compose.yml 里容器启动时会自动执行。✅ 写在 Dockerfile 的CMD/ENTRYPOINT中对应之前示例dockerfile# Dockerfile 末尾 CMD [python, -m, debugpy, --listen, 0.0.0.0:5678, --wait-for-client, app.py]✅ 写在 docker-compose.yml 的command中yamlservices: app: build: . ports: [5678:5678] # 容器启动时自动执行该命令 command: python -m debugpy --listen 0.0.0.0:5678 --wait-for-client app.py方式 2手动进入容器内部执行调试 / 排查用如果想临时调试或容器已启动可手动登录容器执行先启动一个基础容器暴露端口映射代码bash运行# 启动容器后台运行映射端口和代码 docker run -it -d -p 5678:5678 -v $(pwd):/app --name debug-container python:3.10-slim进入容器的交互式终端bash运行# 登录容器进入容器内部的命令行 docker exec -it debug-container /bin/bash在容器内切换到代码目录执行命令bash运行# 容器内执行先安装 debugpy再启动调试 cd /app # 切换到代码所在目录必须和你的代码路径一致 pip install debugpy python -m debugpy --listen 0.0.0.0:5678 --wait-for-client app.py二、关键注意事项新手必看执行目录必须正确命令中的your_application.py是容器内的路径必须确保执行命令时的工作目录能找到这个文件比如用cd /app切换到代码目录。必须安装 debugpy执行命令前容器内必须先装debugpy可写在 Dockerfile 里或手动pip install debugpy。端口必须暴露启动容器时要加-p 5678:5678映射端口否则 VS Code 连不上容器内的 5678 端口。总结日常开发优先把命令写在 Dockerfile/docker-compose.yml 中容器启动时自动执行无需手动操作临时调试可通过docker exec -it进入容器在容器内的代码目录执行该命令核心前提容器内安装 debugpy 端口映射 5678 执行目录能找到目标 Python 文件。参考二第一步先确认容器内的 debugpy 服务是否正常运行这是最核心的前提先通过命令行验证容器侧状态1. 检查容器是否在运行bash运行# 查看所有运行中的容器 docker ps # 如果容器没运行先启动docker start 容器名/容器ID如果容器未运行 → 先启动容器再继续排查。2. 进入容器检查 debugpy 是否在监听 5678 端口bash运行# 进入容器终端 docker exec -it 你的容器名/容器ID /bin/bash # 在容器内执行检查 5678 端口是否被占用 netstat -tulpn | grep 5678 # 或用 python 检查如果没有 netstat python -c import socket; s socket.socket(socket.AF_INET, socket.SOCK_STREAM); print(s.connect_ex((0.0.0.0, 5678)))✅ 正常结果netstat能看到python进程监听0.0.0.0:5678python命令返回0端口可连接。❌ 异常结果无输出 / 返回111→ 说明 debugpy 没启动重新执行bash运行# 容器内重新启动 debugpy替换为你的脚本路径 pip install debugpy # 确保安装 python -m debugpy --listen 0.0.0.0:5678 --wait-for-client /app/你的脚本.py3. 本地测试能否连接容器的 5678 端口bash运行# 本地执行Windows 用 telnet 或 PowerShell telnet localhost 5678 # 或 PowerShellTest-NetConnection localhost -Port 5678✅ 正常连接成功 /TcpTestSucceeded: True。❌ 异常连接拒绝 → 检查容器启动命令是否加了-p 5678:5678端口映射重新启动容器bash运行docker run -d -p 5678:5678 --name 容器名 镜像名第二步检查 VS Code 调试配置launch.json配置错误是断点 / 调试无反应的高频原因重点核对以下项1. 完整的正确配置模板直接替换你的 launch.jsonjson{ version: 0.2.0, configurations: [ { name: Python: Attach to Docker, type: debugpy, request: attach, connect: { host: localhost, port: 5678, timeout: 10000 // 增加超时时间避免连接慢导致无响应 }, pathMappings: [ { localRoot: ${workspaceFolder}, // 本地项目根目录必须正确 remoteRoot: /app // 容器内代码路径必须和容器内实际路径一致 } ], justMyCode: false, logToFile: true // 开启日志方便排查 } ] }2. 重点核对 3 个关键项port必须和容器内 debugpy 监听的端口一致默认 5678。pathMappingslocalRoot本地项目路径比如你的项目在D:\code\python-docker就写这个路径或用${workspaceFolder}但要确保 VS Code 打开的是项目根目录。remoteRoot容器内代码的实际路径比如你在 Dockerfile 中WORKDIR /app或挂载本地代码到/app就写/app。❗ 路径不匹配 → 调试无反应 / 断点不命中。host本地调试填localhost即可不要填容器 IP。第三步VS Code 侧的额外排查1. 检查扩展是否正常确保安装了Python微软官方和Docker扩展且版本最新。重启 VS Code有时扩展加载异常会导致调试无响应。2. 查看调试日志定位具体错误按F1→ 输入Python: Show Debug Log→ 打开日志面板。再次按 F5 启动调试查看日志中的错误信息Connection refused→ 端口映射 / 容器服务问题。Path mapping not found→ 路径映射错误。Timeout→ 网络 / 容器启动慢增加timeout配置。3. 确认断点是否有效断点需打在可执行代码行比如函数内、循环内不要打在注释、空行、import 行。断点图标是红色实心点→ 有效灰色空心点 → 无效路径映射错误 / 代码未加载。第四步最简验证方案快速定位问题如果以上排查仍无反应用以下极简步骤重新验证新建一个空项目创建app.pypython运行print(开始调试) a 1 b 2 c a b # 在这里打断点 print(f结果{c})创建DockerfiledockerfileFROM python:3.10-slim WORKDIR /app COPY app.py . RUN pip install debugpy CMD [python, -m, debugpy, --listen, 0.0.0.0:5678, --wait-for-client, app.py]构建并启动容器bash运行docker build -t test-debug . docker run -p 5678:5678 --name test-debug-container test-debug按之前的步骤配置launch.json然后按 F5 调试。如果这个极简示例能正常调试 → 说明你的原项目配置 / 代码有问题。如果仍无反应 → 检查 VS Code / 系统环境比如防火墙拦截 5678 端口。总结核心前提容器内 debugpy 必须监听 5678 端口且本地能连接该端口telnet localhost 5678验证。关键配置launch.json中的pathMappings必须精准匹配本地 / 容器代码路径。快速验证用极简项目排除代码 / 配置复杂度定位问题根源。