直接docker run报ModuleNotFoundError，根本原因是未挂载项目目录且依赖未持久化安装：pip install -r requirements.txt在临时容器中执行后退出即丢失，而VSCode默认不自动挂载、构建或复用镜像，需在Dockerfile中用COPY和RUN预装依赖，并在.devcontainer/devcontainer.json中显式配置mounts或workspaceFolder确保文件同步。
为什么直接 docker run 会报 “ModuleNotFoundError”
不是 Python 没装，而是你没把当前项目目录挂载进容器，pip install -r requirements.txt 装的包只存在于临时容器里，退出就丢。VSCode 默认不自动挂载、不自动构建、不自动复用镜像，靠手动敲命令很容易漏掉 -v 或写错路径。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 确保
dockerfile中COPY . /app后有RUN pip install -r requirements.txt，而不是在运行时才装（那样每次都要重装） - VSCode 的
.devcontainer/devcontainer.json必须显式声明"mounts"或依赖"workspaceFolder"自动挂载 —— 否则编辑器看到的文件和容器里运行的不是同一份 - 别用
python:3.12-slim镜像跑带 pandas/numpy 的项目，编译依赖缺失会导致pip install失败，换python:3.12或加build-essential
devcontainer.json 里哪些字段真影响“一键净化”
所谓“净化”，本质是每次打开文件夹都拉起全新容器、不复用旧状态。关键不在“一键”，而在配置是否切断所有隐式状态继承。
实操建议：
立即学习“Python免费学习笔记（深入）”；
-
"remoteWorkspaceFolder"设为"/workspace"，避免和宿主机~/.vscode冲突； - 删掉
"features"下的ghcr.io/devcontainers/features/python—— 它会偷偷往镜像里塞全局 site-packages，破坏“干净”前提； - 加上
"postCreateCommand": "pip uninstall -y $(pip list --format=freeze | cut -d'=' -f1)"，强制清空非requirements.txt安装的包； -
"customizations.vscode.settings"里禁用"python.defaultInterpreterPath"，防止 VSCode 缓存宿主机解释器路径
调试时断点不生效？检查容器内 __pycache__ 和路径映射
VSCode 调试器通过 ptvsd 或 debugpy 连接容器，但断点位置必须和容器内实际执行的源码路径完全一致。常见问题是宿主机路径被映射成不同路径，或容器内生成了 __pycache__ 导致调试器加载了旧字节码。
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在
devcontainer.json中设置"containerEnv": { "PYTHONDONTWRITEBYTECODE": "1" }，禁用缓存； - 确认
launch.json的"justMyCode": true，并设"pathMappings"：例如{ "/workspace": "${workspaceFolder}" }； - 不要在
Dockerfile中用COPY . /tmp/然后WORKDIR /tmp—— 这会让 VSCode 调试器找不到原始文件位置； - 运行前手动执行
docker exec -it <container> rm -rf /workspace/__pycache__，比等它自动清理更可靠
怎么验证环境真的“净化”了
不能只看 pip list 有没有多出包，得测运行时行为：比如装了 requests 但没写在 requirements.txt，它仍能 import 成功，但换台机器就崩。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在容器内执行
pip list --outdated --format=freeze | wc -l，输出非 0 就说明有非声明依赖； - 改一个
requirements.txt里的版本号，重建容器后运行python -c "import pkg; print(pkg.__version__)"，结果必须匹配新版本； - 删掉本地
~/.cache/pip后重试devcontainer rebuild，如果构建失败，说明 Dockerfile 里用了--find-links或私有源但没配credentials
真正麻烦的是跨平台差异：macOS 上跑通的 numpy 构建，在 Linux 容器里可能因 glibc 版本卡住。这类问题不会报错，但运行时 core dump —— 得在 CI 里用相同 base 镜像做 smoke test，而不是只信本地 VSCode 点一下就完事。
