Python同文件夹多模块导入报错：common.database无crud_wrapper

项目文件结构如下：

app/
  entity/
    schema.py 
common/
  database/
    __init__.py
    conn.py
    crud_wrapper.py

在app/entity/schema.py中执行以下导入：

from common.database.conn import classA
from common.database.crud_wrapper import classB

其中classB的导入返回错误：No name crud_wrapper in module common.database，但classA可正常导入，且crud_wrapper.py文件及classB类均存在且无语法错误。请问这是循环导入问题，还是此类导入需要额外步骤？

这种情况基本不是循环导入（循环导入通常会报ImportError: cannot import name或明确的循环依赖错误，而非找不到模块），更可能是以下原因导致：

1. __init__.py配置限制

   • 检查common/database/__init__.py文件，如果里面定义了__all__列表但未包含crud_wrapper，或者有其他限制子模块导出的代码，就会导致直接从common.database导入子模块失败。
   • 解决：要么删除__init__.py里的__all__限制（如果不需要），要么把'crud_wrapper'添加到__all__列表中；也可以改用相对路径导入，比如from ...common.database.crud_wrapper import classB（更推荐修复__init__.py的导出配置）。

2. Python路径未包含项目根目录

   • 如果运行schema.py时，项目根目录没被加入Python的sys.path，Python无法识别common作为顶级包，就会出现模块查找失败。
   • 解决：可以在schema.py开头添加代码临时添加路径：

     import sys
     from pathlib import Path
     sys.path.append(str(Path(__file__).parent.parent.parent))
     

     或者通过设置环境变量PYTHONPATH指向项目根目录，确保Python能正确定位common包。

3. 文件名大小写不匹配

   • 在Linux/macOS系统中文件名区分大小写，如果实际文件名是CRUD_Wrapper.py但导入语句写的是crud_wrapper，就会触发找不到模块的错误。
   • 解决：核对文件名和导入语句的大小写是否完全一致。

4. 缓存干扰

   • Python的字节码缓存（__pycache__文件夹）或IDE的缓存可能导致模块识别异常。
   • 解决：删除项目中所有__pycache__文件夹，重启IDE后重新尝试导入。

内容的提问来源于stack exchange，提问作者Wonseok Choi