FastAPI无法找到自定义Python包的问题排查与解决求助

问题分析 #

当前项目结构：

stack_overflow_mwe/
├── my_package/
│   ├── __init__.py
│   └── my_module.py  # 假设此处定义了my_value
└── fastapi/
    └── fastapi_mwe.py

执行fastapi dev fastapi/fastapi_mwe.py时，Python解释器的工作目录通常是stack_overflow_mwe/，但FastAPI CLI运行时不会自动将项目根目录加入PYTHONPATH，导致无法识别my_package。

修复方案 #

方案1：临时设置PYTHONPATH后启动服务 #

进入stack_overflow_mwe目录，通过终端命令临时设置PYTHONPATH再启动FastAPI：

• Linux/macOS：

  export PYTHONPATH=$(pwd) && fastapi dev fastapi/fastapi_mwe.py
  

• Windows（PowerShell）：

  $env:PYTHONPATH = Get-Location; fastapi dev fastapi/fastapi_mwe.py
  

此方式无需修改代码或项目结构，每次启动前执行即可。

方案2：在FastAPI入口文件动态添加项目根目录 #

在fastapi_mwe.py开头添加代码，自动将项目根目录加入Python路径：

import os
import sys

# 获取当前文件所在目录（fastapi/）
current_dir = os.path.dirname(os.path.abspath(__file__))
# 推导项目根目录（stack_overflow_mwe/）
project_root = os.path.dirname(current_dir)
# 若根目录不在PYTHONPATH则添加
if project_root not in sys.path:
    sys.path.append(project_root)

# 正常导入自定义包
from my_package.my_module import my_value

此方式一劳永逸，无需手动设置环境变量，也不会改变包的位置。

方案3：用.env文件管理环境变量 #

在项目根目录创建.env文件：

PYTHONPATH=/实际路径/stack_overflow_mwe

安装python-dotenv包：

pip install python-dotenv

在fastapi_mwe.py开头加载.env文件：

from dotenv import load_dotenv
import os
import sys

load_dotenv()
project_root = os.getenv("PYTHONPATH")
if project_root and project_root not in sys.path:
    sys.path.append(project_root)

from my_package.my_module import my_value

注意替换文件中的实际路径为你的stack_overflow_mwe目录绝对路径。

验证方式 #

在fastapi_mwe.py中添加代码打印当前路径，确认项目根目录已被加入：

print("当前PYTHONPATH:", sys.path)

启动服务后若能看到stack_overflow_mwe的路径，说明设置生效，导入操作不会再报错。

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