修改sys.path后反而找不到模块，是因为优先插入路径易导致同名模块覆盖（如json.py）、破坏相对导入逻辑、引发循环导入错误，且该操作仅临时生效、不适用于包结构和部署场景。
为什么修改 sys.path 后反而找不到模块？
直接往 sys.path 开头插入路径（比如用 sys.path.insert(0, '/my/lib')）看似能优先加载自定义模块，但极易破坏标准库或第三方包的相对导入逻辑。尤其当你的路径里恰好有同名模块（如 json.py、requests.py），Python 会先加载它，然后报错：ImportError: cannot import name 'XXX' from partially initialized module——这是循环导入的典型信号。
- 优先插入路径只适合极简脚本，不适用于含
__init__.py的包结构 -
sys.path是运行时列表，重启 Python 解释器后失效，无法解决部署一致性问题 - IDE（如 PyCharm）和 CLI 运行时的
sys.path可能不同，导致“本地能跑，CI 报错”
用 -m 启动 + 正确的包结构替代手动改 sys.path
真正可控的方式是让 Python 自己识别包边界，而不是靠路径硬塞。前提是项目结构清晰：
myproject/
├── __init__.py
├── main.py
└── utils/
├── __init__.py
└── helper.py
此时应从 myproject 目录外运行：
python -m myproject.main
立即学习“Python免费学习笔记（深入）”；
- 必须保证
myproject所在目录在PYTHONPATH中，或当前工作目录就是其父目录 -
main.py内可用from utils.helper import xxx，无需任何sys.path操作 - 如果非要从子目录启动，加
-m会失败——Python 要求模块名对应文件系统路径，不能跨级跳转
pyproject.toml 配置 packages 或 find 更适合发布场景
当你需要把代码打包成 wheel 或上传 PyPI，硬编码 sys.path 或依赖当前目录完全不可行。现代方式是用 setuptools 声明包范围：
[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "mylib"
version = "0.1.0"
[project.packages]
find = {where = ["src"], include = ["mylib*"]}
配合目录结构：
src/
└── mylib/
├── __init__.py
└── core.py
- 安装时（
pip install -e .）会自动把src加入sys.path，且仅对当前环境生效 - 不推荐用
packages = ["mylib"]手动列名——漏写一个子包就导致导入失败 - 若用 Poetry，对应的是
[[tool.poetry.packages]]，原理相同，但配置位置不同
调试时快速验证 sys.path 和模块来源
遇到导入异常，别急着改路径，先确认 Python 到底加载了哪个文件：
import json; print(json.__file__)
输出类似 /path/to/myproject/json.py 就说明你覆盖了标准库；如果是 /usr/lib/python3.11/json/__init__.py，问题就不在路径上。
- 检查
sys.path顺序：import sys; [print(p) for p in sys.path] - 临时屏蔽可疑路径：
sys.path = [p for p in sys.path if 'myhack' not in p]，再试导入 - 注意
.pth文件：某些包（如 conda 环境）会在site-packages下放.pth文件，它们也会动态修改sys.path，比代码更隐蔽
路径冲突的本质不是“找不到”，而是“找错了”。盯住 __file__ 和实际路径，比反复调整 sys.path 高效得多。
