Python跨目录导入带依赖脚本的相对路径问题解决方法

问题根因 #

Python导入模块的搜索路径默认以启动脚本所在目录为基准，叠加sys.path中预置的路径，不会随当前执行到哪个脚本自动切换搜索基准，所以子目录脚本里写的同层级/下级依赖导入，会因为搜索路径不对找不到文件。

推荐方案（符合Python官方规范，无兼容问题） #

先明确目标目录结构：

Main Folder/  # 项目根目录，也就是你运行主脚本的目录
├── main.py  # 入口主脚本
└── Subfolder1/  # 一级功能子目录
    ├── func_a.py  # 子目录功能脚本
    └── SubSubfolder1/  # 二级依赖子目录
        └── dep_b.py  # 底层依赖脚本

• 给所有存放Python代码的子目录添加空的__init__.py文件，将目录标记为标准Python包，调整后结构：

  Main Folder/
  ├── main.py
  └── Subfolder1/
      ├── __init__.py  # 空文件即可，不需要写任何代码
      ├── func_a.py
      └── SubSubfolder1/
          ├── __init__.py  # 空文件即可
          └── dep_b.py
  

• 所有导入语句统一以项目根目录（Main Folder）为基准写绝对导入，不要写基于脚本自身位置的相对路径导入：
  • 主脚本main.py导入子目录功能脚本：from Subfolder1 import func_a
  • 子目录脚本func_a.py导入下级依赖：from Subfolder1.SubSubfolder1 import dep_b
• 启动脚本时固定在Main Folder目录下执行python main.py即可，不管脚本嵌套多少层，导入都不会出路径问题，项目迁移到其他设备也能直接跑。

老代码兼容方案（无需修改原有导入逻辑） #

如果是已经写好的老项目，不想逐行调整导入语句，可以在每个存在内部依赖导入的子目录脚本最顶部（所有内部依赖导入之前）加入以下代码，自动将当前脚本所在的绝对路径加入Python搜索路径：

import sys
import os
sys.path.append(os.path.dirname(os.path.abspath(__file__)))

加完之后，func_a.py里原来写的from SubSubfolder1 import dep_b这类基于脚本自身目录的导入就可以正常生效，不需要额外调整运行命令。

注意：该方案仅用于老项目快速兼容，不要和上面的标准包方案混用，避免出现模块重复导入的问题。

避坑提醒 #

• 不要用os.chdir()切换程序运行目录解决导入问题，会全局修改程序工作路径，后续文件读写逻辑很容易出现路径错误。
• 不要在代码里硬编码项目的绝对路径，换部署环境会直接失效。
• 不要随意修改系统全局PYTHONPATH环境变量，项目迁移、多版本并行时很容易出现配置冲突。

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