解决Windows服务器非Poetry环境下的Python相对导入报错问题

问题原因 #

直接执行python tool1.py时，Python会将tool1.py所在的all_tools/tool1/tool1/目录视为顶级包，导致原本在Poetry环境下可用的绝对导入from config.config_loader.config_loader import Config无法找到config包；而尝试多级相对导入时，又因为超出了Python认定的顶级包范围，触发ImportError: attempted relative import above top-level package错误。

可行解决方案 #

方案1：临时将all_tools目录添加到Python路径 #

在tool1.py的最顶部添加以下代码，手动把项目根目录（all_tools）加入Python的模块搜索路径：

import sys
from pathlib import Path

# 获取all_tools目录的绝对路径
project_root = Path(__file__).parent.parent.parent
sys.path.append(str(project_root))

# 之后就可以用原来的绝对导入
from config.config_loader.config_loader import Config

class Tool1(Config):
    # 你的业务代码

说明：Path(__file__).parent.parent.parent的层级对应你的目录结构：tool1.py的父目录是all_tools/tool1/tool1/，往上两级就是项目根目录all_tools。

方案2：以模块方式运行脚本 #

在PowerShell中，切换到all_tools的上级目录（注意不是all_tools内部），然后用-m参数以模块形式运行tool1.py：

# 假设all_tools所在路径是D:\projects\all_tools，先切换到上级目录D:\projects
cd D:\projects
# 以模块方式运行目标脚本
python -m all_tools.tool1.tool1.tool1

说明：这种方式会让Python把all_tools识别为顶级包，和Poetry环境下的模块结构一致，原来的绝对导入代码不需要修改。

方案3：调整为正确的相对导入 #

如果想使用相对导入，需要确保运行方式是模块模式（同方案2），然后把导入语句改成相对于tool1包的路径：

# 从当前tool1包出发，往上两级找到config包
from ...config.config_loader.config_loader import Config

class Tool1(Config):
    # 你的业务代码

注意：这种方式下不能直接运行python tool1.py，必须用方案2中的python -m命令运行，否则依然会触发相对导入超出顶级包的错误。

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