Python项目根目录__init__.py引发导入问题：解决方案与合理性探讨

项目结构 #

pysbx/
    calculator/
        calc.py
        __init__.py
    tests/
        test_calc.py
        __init__.py
    __init__.py

遇到的问题 #

• 直接运行测试代码test_calc.py时，无论是用import calculator.calc还是from pysbx.calculator.calc import Calculator都会导入失败
• 但执行python.exe -m unittest discover -v命令时，测试却能正常跑通
• 把根目录的__init__.py删掉后，所有导入问题都消失了

测试代码如下：

import unittest

#from pysbx import calculator
from calculator.calc import Calculator

class TestCalculations(unittest.TestCase):

    def test_sum(self):
        calc = Calculator(8, 2)
        self.assertEqual(calc.get_sum(), 10, 'The sum is wrong.')

if __name__ == '__main__':
    unittest.main()

问题本质 #

根目录的__init__.py会把pysbx标记成一个Python包，而非普通的项目根目录。当你直接运行test_calc.py时，Python会自动把tests/所在的目录加入模块搜索路径（sys.path），但不会把pysbx的父目录加进去。这就导致：

• 用import calculator.calc时，Python在tests/下找不到calculator子包
• 用pysbx.calculator.calc时，因为pysbx不在搜索路径里，同样找不到对应的模块

而python -m unittest discover命令会自动把项目根目录（pysbx的父目录）加入sys.path，能正确识别pysbx包和它的子模块，因此测试可以正常运行。

修复方案 #

方案1：直接删除根目录的__init__.py #

这是Python 3.3+最推荐的做法。Python 3.3之后支持命名空间包，不需要__init__.py来标记包结构。删掉该文件后，pysbx作为普通项目根目录，其所在父目录会被Python识别为模块搜索路径的一部分，calculator可以直接导入，后续打包安装后pysbx.calculator也能正常引用。

方案2：调整导入方式和运行命令（保留根目录__init__.py） #

如果必须保留根目录的__init__.py，可以这么操作：

• 测试代码使用绝对导入：from pysbx.calculator.calc import Calculator
• 运行测试时必须从pysbx的父目录执行命令，比如：

  python -m tests.test_calc
  

  或者手动设置PYTHONPATH环境变量，把pysbx的父目录加入：

  # Windows
  set PYTHONPATH=你的pysbx父目录路径
  python pysbx/tests/test_calc.py
  
  # Linux/macOS
  export PYTHONPATH=你的pysbx父目录路径
  python pysbx/tests/test_calc.py
  

方案3：用打包工具安装项目 #

通过setup.py或pyproject.toml将项目以开发模式安装到Python环境（执行pip install -e .），这样pysbx会被加入全局模块搜索路径，无论在哪里运行代码都能正确导入。

移除根目录__init__.py是否可行？ #

完全可行，甚至是推荐操作：

• 不会影响项目的打包、安装和正常导入
• 能避免很多本地运行时的路径问题
• 符合Python 3.3+的命名空间包规范，让项目结构更灵活

重构含根目录__init__.py的旧代码 #

如果接手的老项目存在该文件，重构可按以下步骤进行：

1. 测试环境验证：先删除根目录的__init__.py，运行所有单元测试和功能测试，检查是否有导入报错
2. 修复导入路径：若有代码使用from pysbx import ...的绝对导入，本地运行时可能需要调整；但通过安装方式运行的代码通常无需修改
3. 更新文档与脚本：把原来需要设置PYTHONPATH或特定运行目录的说明，改为直接运行的方式
4. 逐步迁移：项目较大时，可先在部分模块测试移除后的效果，确认无问题后再全项目推广

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