模块名冲突是importerror高发原因，自定义包名若与标准库（如json、http）或第三方库（如requests）同名，python会优先加载已安装版本；需用importlib.util.find_spec()检查路径，并清理__pycache__及.pyc文件。
检查包名是否撞上标准库或第三方库
自定义包名和标准库（比如 json、email、http）或常用第三方库（比如 requests、numpy）同名，是导致 ImportError 或静默加载错误的高发原因。Python 会优先加载已安装的同名模块，而不是你本地写的那个。
- 运行
importlib.util.find_spec('your_package_name')，看返回的origin路径是不是指向了标准库或site-packages，而不是你的项目目录 - 临时重命名你的包（例如从
email改成myemail），再试导入——如果成功，基本坐实冲突 - 不要用
pip show your_package_name查，它只查已安装包；而你要防的是“名字被占了但没装”，Python 仍会拦截导入
为什么 .pyc 缓存会让问题更难排查
即使你改了包名、删了旧文件，Python 仍可能从残留的 __pycache__ 或 .pyc 文件里加载旧模块，尤其是当你在不同 Python 版本间切换时。这些缓存不会自动更新，也不会报错，只会默默加载一个“看起来存在但行为异常”的模块。
- 手动删掉所有
__pycache__目录和顶层的*.pyc文件（包括子目录里的） - 加个启动检查：在入口脚本开头加
import your_package; print(your_package.__file__)，确认路径是你预期的源码位置 - IDE（如 PyCharm）有时会缓存 import 解析结果，重启解释器或清缓存（File → Invalidate Caches）比重启更有效
相对导入失败却报 ImportError 的真实原因
当看到 ImportError: attempted relative import beyond top-level package，表面是语法错，实际是运行上下文不匹配——Python 把你当前脚本当成了顶层模块（__name__ == '__main__'），而非包内一部分，所以 from .. import xxx 失效。
- 绝对不能直接双击运行或用
python dir/subpkg/module.py启动含相对导入的文件 - 必须用
python -m mypackage.subpkg.module方式运行，且确保my_package所在目录在sys.path中（通常是当前工作目录） -
__init__.py文件必须存在，哪怕为空；Python 3.3+ 的隐式命名空间包不支持相对导入
IDE 运行和命令行不一致的根本差异
PyCharm / VS Code 默认把当前打开的文件所在目录设为工作目录，并可能自动把项目根加进 sys.path；而终端里你 cd 到哪、怎么调用 python，sys.path 就完全不一样。同一个 import 语句，在两个环境里可能一个成功、一个报 ModuleNotFoundError。
- 在代码开头加
import sys; print(sys.path[0])，一眼看出“当前脚本所在目录”是不是你认为的包根目录 - PyCharm 中右键目录 → Mark Directory as → Sources Root，等价于把该路径插入
sys.path[0] - VS Code 需在
.vscode/settings.json里配"python.defaultInterpreterPath"和"python.testing.pytestArgs"，否则测试运行路径容易错位
print(__file__) 和 print(sys.path[0])——90% 的问题，到这里就露馅了。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
