VSCode远程调试本地Docker容器Python代码：断点与路径映射问题

一、关联本地仓库代码，让本地断点命中容器进程 #

当前问题是VSCode调试时加载的是容器内的源码路径，导致本地断点无法匹配。通过配置VSCode调试的路径映射即可解决：

1. 确认路径对应关系

   • 本地Sphinx源码根目录（比如你克隆的Sphinx仓库路径）：${workspaceFolder}/sphinx
   • 容器内Sphinx的安装路径：/opt/venv/python3.10/site-packages/sphinx（根据你的容器实际路径调整）

2. 修改VSCode的launch.json
   在调试配置中添加pathMappings字段，将本地路径映射到容器内路径：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Attach to Docker Sphinx",
               "type": "python",
               "request": "attach",
               "connect": {
                   "host": "localhost",
                   "port": 5678
               },
               "pathMappings": [
                   {
                       "localRoot": "${workspaceFolder}/sphinx",
                       "remoteRoot": "/opt/venv/python3.10/site-packages/sphinx"
                   }
               ]
           }
       ]
   }
   

   如果是调试你自己的文档项目（而非Sphinx核心源码），则映射本地项目根目录到容器内的项目挂载路径（比如本地${workspaceFolder}映射到容器内/app）。

3. 可选：挂载本地源码到容器
   如果你需要修改本地Sphinx源码后直接在容器中生效，启动容器时添加本地源码挂载：

   docker run -v /path/to/local/sphinx:/opt/venv/python3.10/site-packages/sphinx -p 5678:5678 ...
   

   同时在容器内以可编辑模式安装Sphinx：pip install -e /opt/venv/python3.10/site-packages/sphinx，确保本地修改同步到容器。

二、在VSCode中直接浏览容器文件系统 #

使用VSCode的Remote - Containers扩展可以直接连接到运行中的容器，像浏览本地文件一样操作容器内的文件：

• 安装VSCode的Remote - Containers扩展
• 打开左侧的「远程资源管理器」，切换到「Containers」标签
• 找到正在运行的Sphinx容器，右键选择「Attach to Container」
• 进入容器环境后，即可直接浏览/opt/venv、/app等所有容器内的目录，还能直接在VSCode中编辑文件、设置断点调试，无需额外配置debugpy端口映射（扩展会自动处理调试连接）

注意事项 #

• 确保容器内启动debugpy的Python版本与Sphinx使用的Python版本一致
• 启动debugpy时必须指定--listen 0.0.0.0:5678，允许外部连接
• 如果调试第三方依赖（如Sphinx核心），需保证本地源码版本与容器内安装的版本完全一致，否则断点位置会偏移

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