Python import失败的根本原因是sys.path路径配置不当，而非代码错误；它只按sys.path顺序查找模块，不自动搜索任意目录或系统PATH。
Python 的 import 为什么找不到我的模块
根本原因不是代码写错了，而是 Python 没在它“认得”的地方找到文件。它不自动搜你当前目录以外的任意位置，也不看系统 PATH，只查 sys.path 列表里那些路径——而且顺序很重要，靠前的会先被检查、也可能屏蔽后面的同名模块。
- 常见错误现象：
ModuleNotFoundError: No module named 'xxx'，但文件明明存在；或者导入了错误版本（比如本地有个requests.py，结果把官方requests库给盖掉了） - 典型场景：项目结构稍深（如
project/src/utils/helper.py），想从根目录运行脚本却无法 import 同级或子目录下的模块 - 关键参数差异：用
python script.py和python -m package.module触发的查找逻辑完全不同——后者会把当前目录当作包根，前者只把script.py所在目录加进sys.path[0] - 性能影响极小，但错误配置会导致反复 reload 失败、
__pycache__写错位置、甚至 IDE 调试时断点不生效
sys.path 是什么，怎么安全修改它
它是 Python 导入时扫描路径的列表，首项 sys.path[0] 总是执行入口文件所在目录（或空字符串，表示当前工作目录）。别直接 append 或 insert，容易污染全局状态、引发不可复现的导入冲突。
- 推荐做法：在启动脚本开头用
sys.path.insert(1, '/abs/path/to/your/module/dir')，把自定义路径插在sys.path[0]之后、标准库路径之前，避免覆盖内置模块 - 绝对不用
os.chdir()来“凑”路径——这会改变整个进程的工作目录，影响日志写入、配置读取等其他逻辑 - 开发期可临时设环境变量：
PYTHONPATH=/path/to/lib，但上线必须移除，否则依赖外部环境，部署即失败 - 注意 Windows 路径分隔符：用
os.path.join()或正斜杠'/src/utils'，别硬写'\src\utils'，否则在sys.path里变成无效路径
为什么 from . import xxx 在脚本里总报 ImportError: attempted relative import
相对导入只在包内有效，且前提是该文件被当作包的一部分加载（即通过 -m 运行），而不是当成普通脚本直接执行。直接双击或 python mypkg/main.py 运行时，__name__ 是 '__main__'，不是 'mypkg.main'，Python 就拒绝解析 .。
- 正确做法：确保有
__init__.py（哪怕空文件），然后用python -m mypkg.main启动 - 如果必须用脚本方式启动（比如需要命令行参数），就改用绝对导入：
from mypkg.utils import helper，并确保mypkg所在目录已在sys.path中 - IDE 运行时可能默认用脚本模式，需手动改运行配置为 “Module mode”，否则调试时一切正常，一打包就崩
- 相对导入层级不能越界：
from ...utils import x在二级子包里会报错，因为最多只能回退到包根
如何确认 Python 实际加载的是哪个文件
别猜，直接看 __file__。任何已成功导入的模块都有这个属性，返回它在磁盘上的真实路径。这是唯一可信的依据，比文件名、IDE 高亮、甚至 which python 都可靠。
立即学习“Python免费学习笔记（深入）”；
- 快速验证：在交互式环境里输
import json; print(json.__file__)，就能看到你用的是系统自带的还是虚拟环境里的副本 - 排查冲突：如果怀疑导入了错误版本，立刻打印
module.__file__和module.__version__（如果有），比翻文档快十倍 - 注意：
__file__在 zip 包或 frozen 可执行文件中可能不存在，此时可用inspect.getfile(module)做兼容 - 最易忽略的一点：同一模块被不同路径多次导入（比如
./a.py和../a.py），Python 会视为两个独立模块，各自维护状态——这就是为什么有时候改了代码却没生效
