PyCharm Professional是硬性前提，社区版不支持；需启用Docker插件、确保Docker守护进程可访问且有权限、选择含必要依赖的镜像（如python:3.12-slim-bookworm）、严格配置路径映射以保障断点调试与文件同步。
PyCharm Professional 是硬性前提
社区版（Community Edition）不支持 Docker 解释器配置，直接打开 Settings > Project > Python Interpreter 会看不到 Add Interpreter > Docker 选项。必须使用 PyCharm Professional，且版本建议 ≥ 2022.3（旧版对 Docker Desktop for Mac/Windows 的 socket 路径兼容性较差）。
Docker 守护进程必须可访问且有权限
PyCharm 需要直连 Docker daemon，不是靠 docker 命令行工具间接调用。常见失败现象是点击 Add Interpreter > Docker > Configuration 后报错：Cannot connect to the Docker daemon at unix:///var/run/docker.sock 或 Windows 上的 connect: connection refused。
- Linux：确认当前用户在
docker用户组中（sudo usermod -aG docker $USER），并重启 shell - macOS / Windows：确保 Docker Desktop 已启动，且在设置中启用了
Allow the Docker daemon to be accessed via TCP (without TLS)（仅限本地开发，不勾选 TLS 选项更省事） - PyCharm 中的
Docker configuration > Docker executable path默认为docker，但若 Docker Desktop 未加入 PATH，需手动填入完整路径，如 macOS：/usr/local/bin/docker；Windows：C:\Program Files\Docker\Docker\resources\bin\docker.exe
选择镜像时别直接用 python:3.12-slim 这类基础镜像
PyCharm 在容器内需要运行调试代理（pydevd）、包管理器（pip）和文件同步服务，基础镜像常缺失 curl、tar、bash 或 glibc，导致解释器添加后立即报错：Failed to initialize interpreter: No module named pydevd 或卡在 “Mounting project files…”。
- 优先选官方带
-slim但非-alpine的镜像，例如：python:3.12-slim-bookworm（Debian Bookworm 基础，兼容性好） - 若坚持用 Alpine（如
python:3.12-alpine），需在Dockerfile中显式安装依赖：apk add --no-cache bash curl tar，否则 PyCharm 启动失败 - “Image name” 输入框支持直接写
registry.example.com/myapp:latest，但首次加载会拉取并构建——注意网络和镜像仓库权限
项目路径挂载和工作目录容易错配
PyCharm 默认把本地项目根目录挂载到容器内 /opt/project，并设为工作目录（Working directory）。但如果你的 requirements.txt 或入口脚本（如 main.py）依赖相对路径（比如读取 ./config.yaml），而容器内实际工作目录是 / 或 /app，就会抛出 FileNotFoundError。
立即学习“Python免费学习笔记（深入）”；
- 务必检查右下角解释器配置面板中的
Path mappings：左边填本地绝对路径（如/Users/me/myproj），右边对应容器内路径（默认/opt/project），两者必须严格一致 - 在
Interpreter options框中可追加-c "import sys; print(sys.path)"快速验证容器内路径是否生效 - 调试时断点不命中？大概率是挂载路径没对齐——PyCharm 依赖源码路径与容器内路径完全匹配才能映射断点
最麻烦的其实是多层嵌套子模块 + 自定义 PYTHONPATH 的项目，Docker 解释器不会自动继承宿主机的环境变量，所有路径逻辑都得在容器内重走一遍。
