Python AttributeError: module has no attribute

症状

出现 AttributeError: module 'X' has no attribute 'Y'。导入本身正常，仅仅是某个属性缺失。它常伴随依赖升级或项目根目录新增文件而出现。

诊断

列出模块实际提供的属性及其加载位置：

import numpy as np
print(np.__file__)
print([a for a in dir(np) if 'nd' in a])

若 __file__ 指向你的项目目录，说明有同名本地文件遮蔽了该包。

修复

对照已安装版本调整调用，并重命名遮蔽文件：

pip show numpy
mv numpy.py legacy_numpy_helper.py
find . -name '*.pyc' -delete

对于可选功能，使用带守卫的导入，而不要假定属性必然存在。

验证

重新运行代码，确认属性可解析。加入一个在 CI 中访问所用属性的冒烟测试，可在部署前捕获未来的版本漂移。