Windows环境下VSCode使用debugpy调试Docker化Django应用时路径映射报错求助

数据老陈

2026-4-21

遇到这种跨系统的路径映射问题真的挺闹心的，结合你说Mac和Ubuntu VM都正常、唯独Windows出问题的情况，大概率是Windows和Linux容器之间的路径格式、大小写处理差异导致的，给你几个针对性的排查和解决思路：

检查路径格式与大小写一致性
Windows系统用反斜杠\作为路径分隔符，且不区分文件名大小写；但Linux容器用正斜杠/，且大小写敏感。你虽然把远程仓库挂载成了Windows盘符，但VSCode传递给debugpy的路径格式可能和容器预期的不匹配。
建议手动将launch.json里的localRoot改成正斜杠格式的绝对路径，比如你的挂载盘符是Z盘，项目根目录在Z:\django-project，就写成"localRoot": "Z:/django-project"；同时确认本地文件的大小写和容器内完全一致（比如本地是views.py，容器里不能是Views.py，Windows不区分但Linux会视为不同文件）。

调整launch.json的路径映射配置
试试在原有pathMappings的基础上，添加resolveSourceMapLocations参数帮助VSCode更精准匹配路径，修改后的配置大概是：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Django debug",
            "type": "python",
            "request": "attach",
            "pathMappings": [
                {
                    "localRoot": "Z:/django-project", // 替换成你的正斜杠格式本地路径
                    "remoteRoot": "/app"
                }
            ],
            "resolveSourceMapLocations": ["${workspaceFolder}/**", "/app/**"],
            "port": 6000,
            "host": "192.168.100.20"
        }
    ]
}

确认debugpy的启动方式正确
虽然你能成功连接调试器，但Windows环境下可能因为启动参数的细节导致路径识别异常。建议修改docker-compose.yml里的command，直接用debugpy启动Django，确保监听端口和路径上下文正确：
```
command: sh -c "python -m debugpy --listen 0.0.0.0:6000 --wait-for-client manage.py runserver 0.0.0.0:8000"
```
这种方式会强制debugpy在启动Django前监听端口，且路径基于容器内的/app目录，减少路径歧义。
通过WSL2中转调试（推荐）
既然Ubuntu VM能正常工作，你可以用Windows的WSL2来中转：把挂载的网络驱动器映射到WSL环境中（比如执行mkdir /mnt/z && sudo mount -t drvfs Z: /mnt/z），然后在WSL里打开VSCode加载项目。此时localRoot用WSL风格的路径（比如/mnt/z/django-project），和容器的/app路径格式完全一致，能完美规避Windows的路径兼容性问题。
同步debugpy和VSCode插件版本
确保Windows端VSCode的Python插件是最新版本，同时容器内安装的debugpy版本和本地VSCode使用的版本尽量一致，版本不匹配也可能导致路径映射逻辑出现偏差。可以在requirements.txt里显式指定debugpy的版本号。

你可以先从调整路径格式和launch.json配置开始尝试，应该能快速定位并解决Windows特有的路径映射问题。

备注：内容来源于stack exchange，提问作者NICOLÁS ANTONIO PINO LEVA