--reload本质是reloader父进程监控文件变化并重启worker子进程，非模块热更新；它与--workers互斥，仅监听.py文件，pycharm 2024+需降级uvicorn==0.20.0方可生效。
用 --reload 参数启动是最直接的方式
只要在命令行里加 --reload，Uvicorn 就会启用文件监听 + 进程重启机制。它不是热更新模块，而是起一个 reloader 父进程监控文件变化，一旦检测到改动（如 main.py 保存），就杀掉当前 worker 进程、拉起新进程加载最新代码。
典型命令是：
uvicorn main:app --reload
注意三点：
-
--reload和--workers不能共存，因为多进程下无法统一管理重载逻辑 - 默认只监听
.py文件，若要监听模板或配置文件（比如.toml），得配合--reload-dir或第三方工具（如 watchfiles 配置） - 如果你用的是 PyCharm 2024+ 版本，
--reload可能失效——这是已知兼容问题，降级到uvicorn==0.20.0能解决
代码内调用 uvicorn.run() 时如何开启重载
在 Python 脚本里用 uvicorn.run() 启动，必须显式传入 reload=True，且整个调用必须包裹在 if __name__ == "__main__": 块中，否则多进程环境下会重复导入、重复初始化。
正确写法示例：
if __name__ == "__main__":
uvicorn.run(
"main:app",
host="127.0.0.1",
port=8000,
reload=True,
workers=1 # reload=True 时 workers 必须为 1，否则报错
)
常见错误：
- 把
uvicorn.run(...)写在模块顶层，导致 import 时就执行，被子进程重复触发 - 设了
workers=4还带reload=True，Uvicorn 会直接拒绝启动并提示冲突 - 传参用了
app=app（实例对象）而不是"main:app"（字符串路径），这在 reload 模式下不支持
环境变量和配置文件也能控制重载开关
Uvicorn 支持通过环境变量或配置文件启用重载，适合容器化部署或 CI/CD 场景。优先级是：命令行 > 编程式参数 > 环境变量。
Uvicorn 0.52.1
下载
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
设置环境变量方式：
export UVICORN_RELOAD="true" uvicorn main:app
或者在配置文件（如 uvicorn_config.py）中写：
uvicorn_config = {
"app": "main:app",
"reload": True,
"host": "0.0.0.0",
"port": 8000,
}
然后启动：
uvicorn --config-file uvicorn_config.py
注意：UVICORN_RELOAD 的值必须是字符串 "true"（小写），"True" 或 1 都不会生效；配置文件里则直接用 Python 布尔值 True。
重载失败的典型表现和快速排查点
改完代码没反应？不是所有改动都会触发重载。常见卡点：
-
Address already in use：上一次重载失败后 worker 进程没彻底退出，端口被占。用lsof -i :8000找 PID 并kill -9掉 - 修改了非
.py文件（比如config.yaml）但没配置--reload-dir，Uvicorn 默认不监听这类扩展名 - 项目结构里缺
__init__.py，导致uvicorn api.main:app报ModuleNotFoundError，重载根本没起来 - 使用了某些全局单例（如数据库连接池、Redis 客户端），重载后这些对象确实重建了，但你没意识到它们的状态已丢失
重载本质是进程重启，不是代码 patch。这点容易被忽略，尤其当你依赖模块顶层的缓存或状态时。
