最常被忽略的路径陷阱是：用相对路径-v ./scripts:/app/scripts映射时，若宿主机路径不存在，docker会静默创建空目录，导致容器内目标路径为空而非预期脚本文件；实操须用绝对路径、映射前确认路径存在且含目标文件、进容器后先ls验证内容。
docker run 时 -v 映射导致脚本变成空目录
最常被忽略的路径陷阱：用 -v ./scripts:/app/scripts 映射一个本地相对路径，而该路径在宿主机上并不存在（比如拼写错误或尚未创建），Docker 会**静默创建一个空目录**挂载进去。容器里执行 python /app/scripts/test.py 就会报 can't find main module in '/app/scripts'——因为那根本不是文件，是空目录。
实操建议：
- 始终用绝对路径做 volume 映射：
-v $(pwd)/scripts:/app/scripts或-v /home/user/project/scripts:/app/scripts - 映射前先确认宿主机路径存在且含目标文件：
ls -l ./scripts/test.py - 进容器后别急着跑脚本，先
ls -l /app/scripts/看是否真有test.py，而不是一个空目录
WORKDIR 不匹配导致 import 失败
Python 的 import 行为严重依赖当前工作目录（CWD）。如果 Dockerfile 里写了 WORKDIR /app，但你实际想从项目根目录运行测试（比如 import src.utils），而 src/ 在 /app/src 下，那必须确保 python 命令是在 /app 下执行的，否则 sys.path[0] 就不是项目根目录。
常见错误现象：
-
ModuleNotFoundError: No module named 'src'—— 脚本在/或/workspace下执行，而非/app -
ImportError: cannot import name 'test_helper'—— 相对导入失败，因为当前模块不在包结构内
解决办法：
- 在
docker run里强制指定工作目录：docker run -w /app ... python scripts/test.py - 或在
CMD中显式切目录：CMD ["sh", "-c", "cd /app && python scripts/test.py"] - 避免依赖隐式 CWD，改用
-m模块方式启动：python -m pytest tests/（前提是tests/在PYTHONPATH或当前目录下）
PYTHONPATH 和 sys.path 的优先级冲突
很多人加了 ENV PYTHONPATH=/app 就以为万事大吉，但 Python 的 sys.path 是有顺序的：sys.path[0] 永远是当前脚本所在目录（不是 WORKDIR），它会**覆盖 PYTHONPATH**。所以如果你在 /tmp 下执行 python /app/scripts/test.py，sys.path[0] 就是 /tmp，哪怕 PYTHONPATH 包含 /app，import src 仍会失败。
关键判断点：
- 运行脚本时，它的「父目录」是否在
sys.path中？不是PYTHONPATH说了算，是脚本路径本身决定sys.path[0] -
python -c "import sys; print(sys.path)"必须在和脚本同级或上层目录执行才能看到真实路径链 - 真正可靠的做法是让脚本在项目根目录执行，或用
-m方式（此时sys.path[0]是当前目录，且模块名按包结构解析）
docker exec 进去后 pwd 显示 /，但脚本却在 /app 下
这是 WORKDIR 和 exec 行为不一致的典型表现。镜像构建时设了 WORKDIR /app，但你用 docker exec -it container_id bash 进去，没加 -w，结果 shell 启动在默认路径（通常是 /），而 python scripts/test.py 就会因路径错乱失败。
验证与修复：
- 查容器默认 WORKDIR：
docker inspect container_id | grep -i workdir，确认是不是/app - 进容器时强制工作目录：
docker exec -w /app -it container_id bash - 或者直接在 exec 里切目录运行：
docker exec -it container_id sh -c "cd /app && python scripts/test.py" - CI/CD 脚本中务必显式带
-w，不能依赖镜像默认值——不同基础镜像默认 WORKDIR 可能是/、/root或/workspace
路径问题从来不是“多试几次就能好”的类型；一旦 WORKDIR、volume 映射、PYTHONPATH、脚本执行位置这四个点中任意一个错位，import 就会静默失败。最稳的方式是：固定 WORKDIR、用绝对路径映射、在 WORKDIR 下执行脚本、必要时用 -m 替代直接执行 .py 文件。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
