跨文件夹导入类失败：ModuleNotFoundError问题排查与解决

问题原因 #

当你在api/main.py中执行from bot import GetCategories时，Python的模块搜索路径（sys.path）未包含bot文件夹所在的项目根目录。因为直接在api目录下运行uvicorn时，Python默认仅将当前工作目录（api文件夹）加入搜索路径，而bot位于上一级目录，因此无法被找到。

解决方案 #

方案1：临时添加项目根目录到PYTHONPATH #

运行uvicorn命令前，先将项目根目录添加到环境变量：

• Linux/macOS：

  export PYTHONPATH="/你的项目根目录绝对路径"
  uvicorn main:app --reload
  

• Windows（命令提示符）：

  set PYTHONPATH=C:\你的项目根目录绝对路径
  uvicorn main:app --reload
  

• Windows（PowerShell）：

  $env:PYTHONPATH = "C:\你的项目根目录绝对路径"
  uvicorn main:app --reload
  

方案2：在main.py中手动添加路径 #

修改api/main.py，在开头加入代码将项目根目录注入sys.path：

import sys
from pathlib import Path

# 获取api文件夹的父目录（即项目根目录）
project_root = Path(__file__).parent.parent
sys.path.append(str(project_root))

from fastapi import FastAPI
from bot import GetCategories

app = FastAPI()

@app.get("/get_categories/{auth_token}")
def read_item(auth_token: str):
    i = GetCategories()
    return 'test'

方案3：将项目作为可安装包（长期项目推荐） #

1. 在项目根目录创建setup.py文件：

from setuptools import setup, find_packages

setup(
    name="your-project-name",
    version="0.1",
    packages=find_packages(),
)

2. 以开发模式安装包：

pip install -e .

完成后无论在哪个目录运行uvicorn，都能正常导入bot模块。

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