Uvicorn启动FastAPI项目教程-Python教程-PHP中文网

Uvicorn 启动 FastAPI 报 ModuleNotFoundError 是因找不到 main.py 文件或其中未定义 app 变量；--reload 仅监听 .py 文件时间戳变化；本地开发用 --host 127.0.0.1 更安全，局域网访问需 --host 0.0.0.0；启动成功不等于接口可用，须手动测试 / 和 /docs。

uvicorn启动fastapi项目教程

Uvicorn 启动 FastAPI 项目，核心就一条命令：uvicorn main:app --reload，但拼错模块名、变量名、路径或环境配置错误，都会导致「找不到应用」或「启动后无法访问」。

为什么 `uvicorn main:app` 会报 ModuleNotFoundError？

这不是 Python 导入失败，而是 Uvicorn 在当前工作目录下找不到 main.py 文件，或文件里没定义名为 app 的变量。

main 是模块名（即 Python 文件名，不含 .py），必须和当前终端所在目录下的文件名完全一致（区分大小写，比如 Main.py ≠ main.py）
app 是变量名，必须是 main.py 中通过 app = FastAPI() 创建的顶层变量，不能在函数/类/条件块内定义
如果文件不在当前目录，需用相对/绝对路径导入：例如 src.main:app（前提是 src/ 是 Python 包，含 __init__.py）
终端执行命令前，先运行 ls main.py（macOS/Linux）或 dir main.py（Windows）确认文件存在

`--reload` 开发模式下哪些改动会触发重载？

Uvicorn 默认只监听 .py 文件变更，但实际生效依赖两个条件：Python 源码变动 + 文件时间戳更新。常见失效场景：

编辑器保存时未真正写入磁盘（如 VS Code 的「延迟保存」或「暂存区预览」），可关掉「Auto Save」并手动 Ctrl+S
使用 WSL 或远程开发时，文件系统挂载方式导致时间戳未更新，建议在 WSL 内部终端执行命令，而非 Windows 命令行
修改了 pydantic 模型或路由装饰器参数（如 @app.post("/v1/users", tags=["user"])），这些属于代码逻辑，会被检测到；但修改 OpenAPI 文档描述字符串（description=...）不会触发重载
不建议在生产环境加 --reload，它会启用 watchfiles 监控进程，增加资源开销且不安全

本地调试时，`host` 和 `port` 怎么设才不踩坑？

默认 uvicorn main:app --reload 绑定的是 127.0.0.1:8000，这会导致某些情况无法访问：

Uvicorn 0.52.1

Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。

下载

想用手机或局域网其他设备访问，必须显式指定 --host 0.0.0.0（不是 * 或空字符串）
端口被占用时，不要直接改 --port 然后硬上，先查占用：lsof -i :8000（macOS/Linux）或 netstat -ano | findstr :8000（Windows）
Docker 容器内运行时，--host 0.0.0.0 是必须的；但本地开发用 --host 127.0.0.1 更安全，防止局域网扫描暴露接口
浏览器访问请认准控制台输出的那行：INFO: Uvicorn running on http://127.0.0.1:8000 —— 不要凭记忆输错协议（http 不是 https）或端口

如何让 `uvicorn.run()` 脚本方式和命令行行为一致？

直接运行 python main.py 时，如果用了 uvicorn.run(...)，必须保证参数对齐，否则热重载、日志级别、绑定地址都可能不一致：

脚本中调用 uvicorn.run() 时，reload=True 必须配合 reload_dirs=["."]（尤其在子目录结构下）
debug=True 不等于 --reload，它只影响 FastAPI 内部异常页面，不影响重载逻辑
避免混用：不要在命令行加 --reload，同时又在脚本里写 reload=True，Uvicorn 会报 ValueError: reload cannot be used with reload_dirs
推荐统一用命令行方式启动，脚本里只保留 app = FastAPI() 和路由定义，保持纯净

最常被忽略的一点：Uvicorn 启动成功后，它只是「开始监听」，并不验证路由是否真的能响应。哪怕你写了 @app.get("/api/user")，但没定义参数类型或返回值，接口仍能启动——直到你用 Postman 或浏览器请求时才抛出 500 错误。所以启动后务必手动测一个根路径 /，再看文档页 /docs 是否能打开。