多层嵌套文件夹Python项目相对导入及ROOT_DIR配置问题求助

核心原因 #

PyCharm会自动将项目根目录加入Python的模块搜索路径sys.path，但终端运行脚本时不会自动做这件事——这就是为什么IDE里能识别导入，终端却报ModuleNotFoundError的根本原因，和加不加__init__.py无关。

两种Pythonic的解决方式 #

方式一：手动将根目录加入搜索路径（适合小型项目） #

在需要导入ROOT_DIR的文件（比如A.py、B.py）开头，先把项目根目录添加到sys.path，再执行导入：

import os
import sys
# 从当前文件目录向上回溯两级，定位到root_dir
root_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '../../'))
sys.path.append(root_path)

from config.definitions import ROOT_DIR

这个逻辑不受运行目录影响，只要项目文件的相对层级不变，就能正常找到模块。

方式二：采用可安装的项目结构（适合中大型项目） #

这是Python官方推荐的规范做法，彻底解决跨目录导入问题：

1. 在root_dir下创建setup.py（或者更现代的pyproject.toml），示例setup.py内容：

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

2. 进入项目根目录，用开发模式安装项目：

   cd root_dir
   pip install -e .
   

3. 之后无论在项目哪个目录，都能直接导入：

   from config.definitions import ROOT_DIR
   

额外提示 #

• 尽量避免从子目录直接运行脚本（比如cd libs/lib_1 && python A.py），推荐从根目录启动：python libs/lib_1/A.py，这种方式Python会自动把根目录加入sys.path。
• Python 3.3+支持命名空间包，__init__.py不再是必须的；如果要维护传统包结构，添加该文件也不会影响导入逻辑。

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