根本原因是debugpy未在容器内安装且5678端口未暴露，导致调试器进程无法与VSCode前端通信；需手动进容器执行pip install debugpy、开放端口、用绝对路径配置program，并确保WebSocket握手通过反向代理。
私有云部署 VSCode（如 Code Server 或 Gitpod 自建实例）后，Python 调试无法命中断点，根本原因不是插件没装，而是调试器进程无法与本地 VSCode 的语言服务器通信——你得手动配通 python 插件的远程调试通道，而不是照搬本地 launch.json。
为什么 Python 插件在私有云里“看起来装了”却不能调试
私有云环境（比如用 Docker 部署的 code-server）默认不启用 Python 插件的调试后端服务。它只加载了前端语法高亮和补全逻辑，但 ptvsd 或 debugpy 这类调试适配器根本没启动，所以 F5 按下去只是跑了个普通进程，断点全是空心圆。
- 现象：左下角显示已选中解释器（如
/opt/conda/bin/python），但按F5后控制台输出无调试信息，断点灰色不生效 - 本质：VSCode 的 Python 扩展依赖一个叫
debugpy的子进程监听本地回环端口（默认5678），而 code-server 容器默认禁止该端口被内部进程绑定，或未将该端口暴露给 Web 前端 - 验证方法：在容器终端执行
ps aux | grep debugpy，通常返回空；再执行python -m debugpy --help，若报ModuleNotFoundError，说明debugpy根本没装进 Python 环境
必须在容器内安装 debugpy 并开放端口
不能只靠 VSCode 插件市场点安装——插件 UI 只改前端行为，debugpy 是运行时依赖，必须进容器手动装。
- 进入你的 code-server 容器：
docker exec -it <container_name> /bin/bash</container_name> - 确认 Python 环境路径（别直接信
which python，要和你在 VSCode 里选的解释器一致）：/opt/conda/bin/python -m pip install debugpy（Conda 环境）或/usr/local/bin/python3 -m pip install debugpy（标准 Python） - 检查是否装成功：
/opt/conda/bin/python -m debugpy --version应输出版本号 - 修改容器启动参数，暴露调试端口（关键！）：
-p 5678:5678（如果用 docker run）；如果是 docker-compose.yml，加ports: ["5678:5678"] - 重启容器使端口映射生效
launch.json 的 request: launch 模式在私有云里要改配置项
本地能用的 "program": "${file}" 在私有云里大概率失败，因为容器内路径和你在浏览器里看到的“工作区路径”不是一回事——code-server 会把挂载目录映射为虚拟路径，但 debugpy 启动时仍按真实文件系统找文件。
- 不要用
${file}，改用绝对路径："program": "/workspace/myproject/main.py"（其中/workspace是你挂载到容器的目录） - 必须显式指定
"console": "integratedTerminal"，否则输出会丢失；"justMyCode": true建议加上，避免断点跳进库代码 - 如果项目依赖相对导入（如
from .utils import helper），还要加"env": {"PYTHONPATH": "/workspace/myproject"} - 完整最小可用配置示例：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Remote Launch",
"type": "python",
"request": "launch",
"module": "debugpy",
"program": "/workspace/myproject/main.py",
"console": "integratedTerminal",
"justMyCode": true,
"env": {
"PYTHONPATH": "/workspace/myproject"
}
}
]
}
调试器连不上？检查三个隔离层
私有云调试失败，90% 出在以下三处之一，且它们彼此独立、必须全部打通：
-
容器网络层：宿主机能否 telnet 通容器的
5678端口？telnet localhost 5678返回连接拒绝，说明容器没暴露或没监听 -
Python 运行时层：容器内
debugpy是否真在监听？netstat -tuln | grep 5678应有LISTEN状态行 -
code-server 权限层：VSCode Web 前端是否被 CSP 策略拦截 WebSocket 连接？打开浏览器开发者工具 → Network 标签页，触发调试后看是否有
ws://.../debugpy请求失败（状态码 0 或 failed）；若有，需在 code-server 启动时加--allow-http和--disable-telemetry，并确认反向代理（如 Nginx）未过滤 WebSocket 升级头
最常被忽略的是最后一项：Nginx 默认不透传 Upgrade 和 Connection 头，导致 debugpy 的 WebSocket 握手直接被截断，表面现象就是“断点不动、控制台没反应”，但容器日志和进程都看似正常。
