如何解决Python项目跨模块导入的ModuleNotFoundError问题

一、先修正项目文件名问题 #

你提供的项目结构里存在重复文件名（example1.py、service1.py各出现两次），这会导致模块识别混乱，先将其修正为example1.py、example2.py和service1.py、service2.py，修正后的结构如下：

exampleProject
├── models   
│   ├── database
│   │   ├── __init__.py
│   │   ├── example1.py
│   │   └── example2.py
└── services
    ├── __init__.py
    ├── service1.py
    └── service2.py

二、生产环境友好的导入方案 #

1. 使用绝对导入（推荐生产环境） #

以项目根目录exampleProject作为导入起点，这是最稳定的跨文件夹导入方式。

从service1.py导入example1.py

在service1.py中编写：

# 导入模块中的指定类/函数
from models.database.example1 import 目标类名/函数名
# 或者导入整个模块
from models.database import example1

从example2.py导入service2.py

在example2.py中编写：

# 导入模块中的指定类/函数
from services.service2 import 目标类名/函数名
# 或者导入整个模块
from services import service2

2. 确保根目录被Python识别的正确方式 #

生产环境禁止手动用sys.path.append，可以通过两种可靠方式让根目录加入Python的路径列表：

• 方式一：以根目录为工作目录运行代码
  打开终端切换到exampleProject的上级目录，然后通过模块方式启动代码：

  python -m exampleProject.services.service1
  

  如果有根目录下的入口文件（比如main.py），直接运行即可：

  python main.py
  

  这种方式会自动将当前工作目录加入sys.path。

• 方式二：将项目安装为可编辑包
  在exampleProject根目录下创建setup.py文件，内容如下：

  from setuptools import setup, find_packages
  
  setup(
      name="exampleProject",
      version="0.1",
      packages=find_packages()
  )
  

  然后在终端执行：

  pip install -e .
  

  这样项目会被安装到Python环境中，任何位置都能直接使用绝对导入，是生产环境的最优实践。

三、新增文件夹后的导入规范 #

后续新增文件夹时，遵循以下规则即可实现无缝跨文件夹导入：

• 每个新增文件夹都保留__init__.py文件（Python 3.3+支持无该文件的命名空间包，但保留可提升兼容性和明确性）
• 始终使用绝对导入，从项目根目录开始逐层指定模块路径
• 避免使用容易产生歧义的相对导入（比如from ..xxx import yyy，不同运行环境下可能出错）

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