Uvicorn热重载需禁用--workers且源码必须为本地目录，典型命令：uvicorn main:app --reload --reload-dir ./src --reload-exclude "*.pyc"；Windows/macOS需pip install watchfiles。
如何用 --reload 启动热重载调试
开发时最常需要的是改代码自动重启，uvicorn 原生支持热重载，但必须满足两个前提：一是不能用 --workers（多进程会干扰文件监听），二是源码路径不能是安装的包（比如从 pip install 装的，得用本地项目目录）。
典型命令：
uvicorn main:app --reload --reload-dir ./src --reload-exclude "*.pyc"
--reload-dir 指定监听目录，默认只监听当前目录；--reload-exclude 可排除缓存文件，避免误触发。注意 --reload 在 Windows 和 macOS 上依赖 watchfiles，Linux 默认用 inotify，如果报 WatchFiles not installed，就装它：pip install watchfiles。
为什么 --log-level debug 看不到请求体
--log-level debug 仅提升日志级别，显示路由匹配、中间件执行等内部流程，但默认不打印 HTTP 请求体或响应体——这是出于安全和性能考虑。真要查原始请求内容，得自己加中间件，或者用 --proxy-headers + 配合反向代理日志（如 Nginx），或者改用 curl -v 或 httpie --print=hb 抓客户端发出的原始数据。
常见误操作：
- 以为
--log-level trace存在（实际不支持，会报错invalid log level） - 在
--reload模式下看到重复日志（因为每次重启都新建 logger 实例，建议关掉--reload单独测日志）
如何让 Uvicorn 绑定到所有接口并暴露端口
默认 uvicorn main:app 只监听 127.0.0.1:8000，外部访问不了。要让局域网设备访问，必须显式指定 --host 0.0.0.0，例如：
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
uvicorn main:app --host 0.0.0.0 --port 8000
但注意：0.0.0.0 不等于“开放给公网”，它只是监听所有本地网络接口；是否能被外网访问，取决于防火墙、路由器端口映射、云服务器安全组等外部配置。开发阶段别在公网服务器上开 --host 0.0.0.0 且不加认证，容易被扫描利用。
调试时遇到 Address already in use 怎么快速释放端口
这个错误说明端口被占，不是 Uvicorn 本身问题，而是上次进程没退出干净。Windows 下可用：
netstat -ano | findstr :8000 && taskkill /PID <code>XXXX</code> /F
macOS / Linux 下更直接：
lsof -i :8000 && kill -9 <code>XXXX</code>
但频繁手动杀太麻烦，建议启动时加 --lifespan off 避免 lifespan hook 卡住退出，或用 --timeout-graceful-shutdown 1 缩短等待时间。更稳妥的做法是写个 shell 封装脚本，启动前先尝试杀旧进程。
真正难排查的是子进程残留（比如用 subprocess.Popen 启了后台任务但没 .wait()），这种不会出现在 lsof 里，得结合 ps aux | grep uvicorn 看完整进程树。
