运行uvicorn main:app报错无法导入main模块，如何解决并显示Swagger UI？

错误成因 #

• 执行uvicorn main:app时的工作目录不是main.py所在目录，导致uvicorn无法定位到目标模块。
• 文件名大小写不匹配：Linux/macOS系统区分文件名大小写，若文件实际是Main.py或MAIN.py，会导致无法识别main模块。
• 目标模块不在Python的搜索路径中：main.py所在目录未被添加到Python的sys.path，Python解释器找不到该模块。
• 虚拟环境问题：激活的虚拟环境未包含FastAPI/uvicorn依赖，或环境与项目所需不匹配（较少见，但可能间接导致模块导入异常）。

解决方法 #

• 切换到正确目录：先通过cd命令进入main.py所在的文件夹，再执行uvicorn main:app。
• 修正文件名：确保文件名为main.py，Linux/macOS下严格匹配大小写。
• 指定模块路径：无需切换目录时，使用--app-dir参数指定项目目录，例如：

  uvicorn main:app --app-dir /home/user/your-fastapi-project
  

• 添加Python路径：将项目目录加入Python搜索路径，Linux/macOS执行：

  export PYTHONPATH=/path/to/your/project
  

  Windows系统执行：

  set PYTHONPATH=C:\path\to\your\project
  

  之后再运行uvicorn main:app。
• 验证模块可导入：先执行python -c "import main"，若报错则排查路径或文件问题，无报错再启动uvicorn。

确保Swagger UI正常显示 #

1. 确认依赖已安装：执行pip install fastapi uvicorn，确保FastAPI和uvicorn都正确安装。
2. 检查main.py代码结构：需正确创建FastAPI实例，示例代码：

   from fastapi import FastAPI
   
   app = FastAPI()
   
   @app.get("/")
   async def root():
       return {"message": "Hello World"}
   

3. 访问Swagger UI：启动服务后，在浏览器中打开http://127.0.0.1:8000/docs（若指定了其他端口，替换为对应端口号，如--port 8001则访问http://127.0.0.1:8001/docs）。
4. 排查访问问题：若无法打开，检查本地防火墙是否限制端口，或是否有反向代理配置拦截请求，确保端口可正常访问。

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