根本原因是Python解释器未在sys.path列出的路径中找到目标模块；Python按sys.path从左到右查找，不自动包含工作目录或递归扫描子目录，且python -m要求包结构合法（含__init__.py）并从父目录执行。
为什么 import 报 ModuleNotFoundError 却找不到模块？
根本原因不是模块写错了，而是 Python 解释器压根没在它搜索的路径里看到你的文件。Python 只查 sys.path 列表里的目录，不自动包含当前工作目录（除非你恰好从模块所在目录运行脚本），也不递归扫描子目录。
常见现象：python main.py 能跑，但 python -m mypackage.main 就报错；或者 PyCharm 里能导入，终端里运行就失败——这基本都是 sys.path 差异导致的。
- 检查方式：在出错位置前加
import sys; print(sys.path)，确认你要的路径是否在列表中 - 注意顺序：Python 按
sys.path从左到右查找，靠前的同名模块会“遮蔽”后面的 - 临时修改有效但不推荐：用
sys.path.insert(0, "/path/to/your/module")—— 这会让路径优先级最高，但一重启就失效，且难维护
怎样让 python -m 正确识别本地包？
python -m 要求目标是合法的 Python 包（即含 __init__.py），并且必须从「包的父目录」执行，不能从包内部或任意路径启动。
比如结构是：project/ → mylib/（含 __init__.py）→ utils.py，那么正确做法是：
立即学习“Python免费学习笔记（深入）”；
- cd 到
project/目录下 - 运行
python -m mylib.utils（注意不是python -m ./mylib/utils） - 如果想直接
import mylib，确保project/在sys.path中（例如通过export PYTHONPATH=$PWD或启动时加-c "import sys; sys.path.insert(0, 'project')"）
__init__.py 是不是空文件就没事？
不是。空的 __init__.py 只是让目录变成包，但不会自动导出子模块。如果你写了 from . import utils 却没在 __init__.py 里显式导入或定义 __all__，外部 from mylib import * 依然看不到 utils。
更关键的是：如果 __init__.py 里有错误（比如导入了不存在的模块、语法错误），整个包都会无法加载，报错信息可能掩盖真实问题。
- 建议在
__init__.py开头加print("loading mylib")快速验证是否被读取 - 避免在
__init__.py中做耗时操作或复杂初始化，否则影响所有导入该包的脚本 - 若模块只供内部使用，不希望被外部
from mylib import xxx直接调用，可在名字前加下划线，如_helper.py
IDE 和终端路径不一致，怎么统一？
PyCharm 默认把项目根目录加进 PYTHONPATH，VS Code 则依赖你打开的工作区和 launch.json 配置。终端里则完全看当前 shell 的 PWD 和环境变量。
最稳妥的跨环境方案是：用 pip install -e . 把本地包“开发安装”进当前 Python 环境。
- 前提：项目根目录下有
setup.py或pyproject.toml（哪怕最简配置） - 执行后，该包名就永久可导入，不受当前路径影响，且代码修改实时生效
- 副作用：如果你有多个同名本地包，它们会互相干扰，此时得用虚拟环境隔离
真正容易被忽略的是：很多开发者反复改 sys.path 或加软链接，却没意识到问题根源在于没有建立清晰的包边界和发布约定。路径问题本质是项目结构问题。
