如何通过Poetry运行FastAPI应用？配置脚本段及解决运行警告

我刚好也踩过一模一样的坑，来给你捋清楚怎么解决：

问题根源 #

你看到的这个警告：

WARNING: You must pass the application as an import string to enable 'reload' or 'workers'

本质是Uvicorn的reload（热重载）和workers（多进程）模式的限制——这俩功能需要通过导入字符串定位你的FastAPI应用，不能直接传内存里的app对象。毕竟热重载要重启进程，多进程要创建子进程，直接传内存对象没法跨进程复用，必须让Uvicorn重新从文件里导入应用才行。

正确的配置步骤 #

第一步：调整代码的启动逻辑 #

先把你的代码改成支持导入字符串的形式，假设你的代码文件叫main.py，修改后内容如下：

import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

def main():
    # 这里用「模块名:对象名」的导入字符串代替直接传app
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True, workers=2)

if __name__ == "__main__":
    main()

第二步：配置pyproject.toml的scripts #

在[tool.poetry.scripts]段，你需要指定模块名:函数名的导入字符串，告诉Poetry要调用哪个启动入口：

[tool.poetry.scripts]
start = "main:main"

• 这里的main:main，第一个main是你的Python文件名（不带.py后缀），第二个main是你定义的启动函数名。

如果你的项目是标准包结构（比如根目录下有myapp文件夹，app对象在myapp.main模块里），那配置要改成：

[tool.poetry.scripts]
start = "myapp.main:main"

第三步：验证启动 #

现在直接运行命令：

poetry run start

就能正常启动应用，而且不会再出现那个警告——Uvicorn能通过导入字符串正确找到你的app，完美支持热重载和多进程模式。

额外小技巧 #

如果你不想写自定义的main()函数，也可以直接在scripts里指定Uvicorn的入口，不过需要把参数整合进去：

[tool.poetry.scripts]
start = "uvicorn.main:run"

然后启动时需要手动传参数：

poetry run start main:app --host 0.0.0.0 --port 8000 --reload --workers 2

但显然写个自定义启动函数更优雅，还能顺便加一些初始化逻辑（比如加载配置、设置日志等）。

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