FastAPI相对导入报错：ValueError: attempted relative import beyond top-level package 求助

兄弟，我来帮你搞定这个头疼的相对导入问题！

你的问题根源其实很简单——运行代码的路径不对。你现在是直接在src/api/目录下执行uvicorn --reload main:app或者python main.py，这时候Python会把api这个目录当成了顶层包。而你在routers的文件里写的from ..dependencies import db_connect，其中的..是想回到api的父目录（也就是src），但Python此时认定api已经是最顶层的包了，自然就会抛出“超出顶层包”的错误。

给你几个实用的解决方案，挑适合你的来：

方案1：从项目根目录运行（最推荐） #

找到你项目的根目录——也就是包含src文件夹的那个目录，然后在这个目录下执行命令：

uvicorn --reload src.api.main:app

这样Python会把src当作包结构的一部分，api是src的子包，routers里的相对导入..dependencies就能正确指向src.api.dependencies，完全在合法的包层级内，不会再报错。

方案2：设置PYTHONPATH环境变量 #

如果你习惯在src/api/目录下运行命令，可以先把src目录添加到Python的环境变量里，让Python能识别整个包结构：

• 如果你用Linux/macOS，在终端执行：

export PYTHONPATH=/你项目的src目录绝对路径:$PYTHONPATH

• 如果你用Windows（PowerShell）：

$env:PYTHONPATH = "你项目的src目录绝对路径;" + $env:PYTHONPATH

设置完之后，再回到src/api/目录运行uvicorn main:app或者python main.py就正常了。

方案3：用可编辑模式安装项目（适合长期维护的项目） #

给你的项目添加一个pyproject.toml文件，然后用pip把项目安装成可编辑模式：

pip install -e .

这样Python会自动识别你的包结构，不管在哪个目录运行都能正确导入，不过这个方法更适合中型以上的项目。

最后再提醒一句：尽量不要直接在包内部的子目录下运行脚本，这是Python相对导入的经典坑，很容易破坏包的层级结构导致报错~

备注：内容来源于stack exchange，提问作者Federico Taschin