Starlette应用必须由ASGI服务器(如Uvicorn)运行,仅app = Starlette()不会启动服务;正确方式是uvicorn.run(app, host="127.0.0.1", port=8000)或命令行uvicorn main:app,且app需为模块顶层变量。

直接运行 Starlette 实例,别写 app = Starlette() 后就停住
Starlette 应用必须被 ASGI 服务器(比如 Uvicorn)调用,它本身不带内置 HTTP 服务。常见错误是只写了 app = Starlette(),然后执行 python main.py —— 这什么都不会启动,也不会报错,只是静默退出。
正确做法是显式调用 uvicorn.run(),或者用命令行启动。两种方式都要求 app 是一个可调用的 ASGI callable(即符合 async def app(scope, receive, send): ... 签名的对象),而 Starlette 类实例恰好满足这点。
- 如果用脚本内联启动:在
if __name__ == "__main__":块里加uvicorn.run(app, host="127.0.0.1", port=8000) - 如果用命令行启动:确保文件里定义了变量名(如
app),再执行uvicorn main:app - 不要把
uvicorn.run()和命令行混用;二者选其一即可,否则会重复初始化或端口冲突
uvicorn main:app 报错 AttributeError: module 'main' has no attribute 'app'
这个错误说明 Python 找不到名为 app 的顶层变量。Starlette 不强制变量名,但 Uvicorn 默认找 app;如果你写了 my_app = Starlette(),就必须显式指定 uvicorn main:my_app。
容易忽略的细节:
- 变量必须在模块顶层定义,不能缩进在函数或条件块里
- 不能写成
app = Starlette(); if __name__ == "__main__": ...后面才赋值 —— 赋值必须在 import 之后、任何条件之前 - 检查是否拼错大小写:
App≠app - 避免循环 import:比如
main.py导入了另一个模块,那个模块又试图导入main.app
开发时用 --reload,但别在生产环境加
--reload 会监听文件变化并自动重启进程,对开发友好,但它依赖 watchfiles 或 watchdog,且会 fork 多个子进程。这些特性在容器或 systemd 管理的生产环境中不仅多余,还可能引发资源泄漏、日志混乱或信号处理异常。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
生产部署应去掉 --reload,改用:
-
--workers N(N 通常为 CPU 核心数 × 2)来横向扩展 -
--host 0.0.0.0+--port 8000显式绑定(别依赖默认值) - 配合反向代理(如 Nginx)处理 TLS、静态文件和连接池
- 用
python -m uvicorn启动,避免 PATH 冲突,尤其在虚拟环境里更可靠
Starlette 路由注册后没生效?检查 app 是否被覆盖
Starlette 的 @app.route、@app.websocket_route 是装饰器,它们修改的是 app 实例内部的路由表。但如果后续代码又写了 app = Starlette(),就会覆盖掉前面注册的所有路由。
典型出错模式:
- 先写
app = Starlette(),再写@app.route("/")—— ✅ 正确 - 但后面又不小心补了一句
app = Starlette(debug=True)—— ❌ 覆盖原实例,所有路由丢失 - 或在不同位置多次赋值给同一变量名(比如配置加载后重新构造
app) - 用
print(app.routes)可快速验证当前路由是否为空列表
Starlette 的灵活性意味着它不会帮你防错,变量名、赋值时机、装饰器执行顺序,全靠你盯住。一旦路由失效,Uvicorn 启动成功但所有请求都返回 404,这种问题最难排查。

















