从外部Python文件以模块方式运行Uvicorn FastAPI服务器报错排查

错误根源 #

你遇到的这个RuntimeError主要有两个原因：

1. Uvicorn热重载的进程启动逻辑：当开启reload=True时，Uvicorn会启动子进程监控文件变化并重启服务。在Windows系统（或非fork机制的系统）中，子进程会重新执行整个入口脚本（即你的test.py），如果test.py没有用if __name__ == '__main__':包裹启动代码，子进程会再次调用start_server()，引发重复启动进程的冲突。
2. Uvicorn应用实例路径错误：你在start_server()里给uvicorn.run()传的第一个参数是"app"，但从外部模块调用时，Uvicorn无法直接找到这个局部定义的应用实例，必须指定完整的模块路径（格式为模块名:实例名）。

解决步骤 #

步骤1：确保uvicornmodule是合法Python包 #

在uvicornmodule目录下创建一个空的__init__.py文件，让Python将其识别为可导入的包。

步骤2：修改main.py中的start_server()函数 #

将uvicorn.run()的第一个参数改为完整的模块路径，让Uvicorn准确定位到FastAPI应用实例：

def start_server():
    uvicorn.run(
        "uvicornmodule.main:app",  # 替换原来的"app"
        host="0.0.0.0",
        port=8765,
        log_level="debug",
        reload=True,
    )

步骤3：修改test.py，添加__name__保护 #

把启动代码放到if __name__ == '__main__':块中，避免子进程重复执行启动逻辑：

if __name__ == "__main__":
    from uvicornmodule import main
    main.start_server()

可选方案：关闭热重载（仅临时测试用） #

如果只是临时测试不需要热重载，可以直接把main.py里的reload=True改成reload=False，这样Uvicorn不会启动子进程，也能避免这个错误，但开发阶段不推荐关闭热重载。

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