Uvicorn启动报错：unrecognized arguments: main:app --reload 求助

• 环境：使用venv虚拟环境
• 代码片段：
  参数解析代码：

  import argparse 
  
  parser = argparse.ArgumentParser()
  parser.add_argument("--host", type=str, default="0.0.0.0", help='default Ip')
  parser.add_argument("--port", type=int, default=18002, help='default port')
  

  启动逻辑代码：

  import uvicorn
  from fastapi import FastAPI
  
  if __name__ == '__main__':
      import uvicorn
      app = create_app()
  
      uvicorn.run(app, host=str(args.host), port=int(args.port))
  

• 启动命令：

  python -m uvicorn main:app --reload
  

• 报错信息：

  error: unrecognized arguments: main:app --reload
  

尝试直接写死host和port调用uvicorn.run(app, host='0.0.0.0', port=18002)，问题依旧。

原因分析 #

1. 命令行启动冲突：用python -m uvicorn main:app --reload时，uvicorn会把main:app、--reload这些参数传递给你的脚本，但你的argparse只定义了--host和--port，无法识别额外参数，导致报错。
2. 代码缺失关键步骤：你只定义了argparse的解析器，但没有调用args = parser.parse_args()来解析参数，直接使用args.host会触发NameError。

解决办法 #

方案1：用uvicorn命令行启动（推荐） #

如果要保留python -m uvicorn的启动方式，不需要在代码里写argparse和uvicorn.run()，直接暴露FastAPI实例即可：

from fastapi import FastAPI

def create_app():
    app = FastAPI()
    # 在这里添加你的路由、中间件等配置
    return app

# 暴露app实例给uvicorn
app = create_app()

启动时直接通过uvicorn传递参数：

python -m uvicorn main:app --reload --host 0.0.0.0 --port 18002

方案2：用脚本直接启动（python main.py） #

如果要通过脚本自身启动并保留参数解析，修改代码如下：

import argparse
import uvicorn
from fastapi import FastAPI

def create_app():
    app = FastAPI()
    # 在这里添加你的路由、中间件等配置
    return app

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument("--host", type=str, default="0.0.0.0", help='default Ip')
    parser.add_argument("--port", type=int, default=18002, help='default port')
    parser.add_argument("--reload", action="store_true", help="Enable auto-reload")
    # 必须执行解析才能获取参数
    args = parser.parse_args()
    
    app = create_app()
    uvicorn.run(app, host=args.host, port=args.port, reload=args.reload)

启动命令改为：

python main.py --reload

或指定参数：

python main.py --host 0.0.0.0 --port 18002 --reload

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