Python项目文件夹与子文件夹导入管理的正确方法咨询

项目结构 #

root directory
    classes
        my_common_class.py
        my_class_1.py
        my_class_2.py
    my_virtual_env
        ...
    my_wonderful_script.py

问题场景 #

my_class_1.py和my_class_2.py继承自my_common_class.py，同时被my_wonderful_script.py调用。为了直接执行类文件做方法测试，目前用了繁琐的try-except导入方式：

try:
    from classes.my_common_class import myCommonClass
except ImportError:
    from my_common_class import myCommonClass

本地虚拟环境下测试和主脚本都能正常运行，但服务器上执行my_wonderful_script.py时出现ModuleNotFoundError: No module named 'my_common_class'。

优雅解决方案 #

方案1：使用相对导入 + 规范运行测试 #

在my_class_1.py和my_class_2.py中改用相对导入：

from .my_common_class import myCommonClass

• 运行my_wonderful_script.py时，原本的绝对导入from classes.my_class_1 import myClass1可以正常工作
• 要直接测试类文件，在项目根目录执行命令：

  python -m classes.my_class_1
  

  这种方式会让Python把classes当作包识别，相对导入就能正常解析。

方案2：将classes转为可安装包（推荐规范做法） #

1. 在classes目录下创建空的__init__.py文件，让它成为Python包：

   classes
       __init__.py
       my_common_class.py
       my_class_1.py
       my_class_2.py
   

2. 在项目根目录创建pyproject.toml（现代Python包配置文件），内容示例：

   [build-system]
   requires = ["setuptools>=61.0"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "classes"
   version = "0.1.0"
   

3. 在虚拟环境中以开发模式安装这个包：

   pip install -e .
   

之后不管是运行my_wonderful_script.py，还是直接执行python classes/my_class_1.py，都可以统一用绝对导入：

from classes.my_common_class import myCommonClass

这是Python项目的标准做法，彻底避免路径问题，也方便后续扩展维护。

方案3：临时添加模块路径（应急方案，不推荐） #

如果不想修改包结构，可在my_class_1.py开头添加代码，把当前文件所在目录加入Python搜索路径：

import sys
from pathlib import Path

# 将当前脚本所在目录添加到Python路径
sys.path.append(str(Path(__file__).parent))

from my_common_class import myCommonClass

这种方式能临时解决路径问题，但不够规范，大型项目中容易导致路径混乱，不建议长期使用。

问题原因 #

服务器环境中，当my_wonderful_script.py导入my_class_1.py时，Python的模块搜索路径是项目根目录，此时from my_common_class import...无法找到同目录下的文件；而本地可能因为IDE自动将classes目录加入搜索路径，或者虚拟环境的配置差异，才没有报错。

内容的提问来源于stack exchange，提问作者Javier Gonzalez Moncayo