根本原因是Python只在sys.path指定路径中查找模块，而非文件系统任意位置；需通过pip install -e .将项目注册为可导入包，或确保sys.path修改在所有import之前且清理缓存。
为什么 import 报错说 “ModuleNotFoundError” 却明明文件存在？
根本原因不是文件找不到，而是 Python 解释器压根没去你放模块的目录里找。它只查 sys.path 列表里的路径，而这个列表默认只包含当前脚本所在目录、site-packages 和标准库路径。如果你的项目结构是多层嵌套（比如 src/utils.py 想导入 src/core/config.py），或者想从外部目录导入，就必须手动把对应路径塞进 sys.path —— 但不能乱塞，顺序和时机很关键。
在代码开头用 sys.path.insert(0, ...) 为什么有时不生效？
常见于运行方式不一致：用 IDE 直接右键运行单个文件，和终端里 python main.py 的工作目录不同，导致相对路径计算出错；或者更隐蔽的问题——模块已被缓存。Python 导入后会把模块对象存进 sys.modules，后续再 import 同名模块直接返回缓存，根本不重新查 sys.path。所以改了 sys.path 之后如果之前失败过，得先清理缓存：
- 确保修改
sys.path的语句在任何import之前执行（哪怕只是import os） - 如果已报错，重启解释器，或手动删
sys.modules中相关键（不推荐用于生产） - 优先用绝对路径：
os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "lib"))，避免依赖当前工作目录
用 setuptools 配 pyproject.toml 做可安装包，比硬塞 sys.path 更可靠
临时改 sys.path 是调试手段，不是工程方案。真正解耦跨目录导入，应该让 Python 把你的项目当“包”来识别。核心就两点：
- 项目根目录下放一个空的
pyproject.toml，内容至少含：[build-system] requires = ["setuptools>=45", "wheel"] build-backend = "setuptools.build_meta"
- 在根目录执行
pip install -e .（注意末尾的点），这样你的模块名就能被全局 import，不再依赖路径拼接 - 此时
src/下的模块可以用from mypkg.core import config这种方式导入，且 IDE 补全、类型检查都正常
别小看这个 -e（editable mode），它本质是往 sys.path 加了一条指向你源码的软链接，但由 pip 统一管理，不会和手写的 insert 冲突，也不会被误删。
遇到 ImportError: attempted relative import with no known parent package 怎么办？
这错误说明你在用 from .. import xxx 这种相对导入，但 Python 并没把你当前文件识别为某个包的子模块。触发条件很具体：该文件必须是作为模块被运行（python -m mypkg.submodule），而不是直接执行（python mypkg/submodule.py）。解决方案只有两个：
- 改用绝对导入，比如
from mypkg.core import config，前提是已通过pip install -e .安装 - 坚持相对导入，就只能用
-m方式运行，且确保该文件所在目录有__init__.py（即使为空） - 绝不要在脚本里写
if __name__ == "__main__":+ 相对导入 —— 这种写法注定失败
相对导入不是语法糖，它是包加载机制的一部分，脱离包上下文就失去意义。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
