uvicorn配置文件非必须但生产环境强烈推荐，需命名为uvicorn_config.py等并用--config显式加载，核心是定义名为uvicorn_config的字典，键名对应命令行参数（短横变下划线），优先级为命令行＞配置文件＞环境变量。
Uvicorn配置文件不是必须的，但生产环境强烈建议用 —— 它能规避命令行参数拼接错误、避免敏感配置硬编码、统一管理多环境差异。
配置文件怎么命名和加载
Uvicorn不强制文件名，但惯例是uvicorn_config.py或config.py；加载时必须用--config参数，不能靠文件名自动识别：
uvicorn main:app --config uvicorn_config.py
注意：--config-file是旧版参数名，已弃用；新版只认--config。如果误写成--config-file，Uvicorn会静默忽略，仍按默认值启动，容易误以为配置生效了。
- 配置文件必须是合法的Python模块，能被
import（不能有语法错误，不能依赖未安装的包） - 文件里定义的变量名无关紧要，关键是要把配置项组织成字典并赋给
uvicorn_config变量（这是Uvicorn约定的入口名） - 不支持YAML/JSON直接加载；想用YAML需额外装
pyyaml，且仍得通过--log-config传给日志系统，而非主配置
配置项必须用字典形式暴露为uvicorn_config
Uvicorn只认一个全局变量名：uvicorn_config。它必须是dict类型，键名要和命令行参数一一对应（去掉--前缀，短横变下划线）：
# uvicorn_config.py
uvicorn_config = {
"app": "main:app",
"host": "0.0.0.0",
"port": 8000,
"workers": 4,
"log_level": "info",
"timeout_keep_alive": 5,
"access_log": True,
}
常见错法：
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
- 写成
config = {...}→ Uvicorn完全无视 - 键名写成
--timeout-keep-alive或timeout_keep_alive_sec→ 启动报unexpected keyword argument - 把
reload=True和workers=4同时设 → Uvicorn会启动失败，因为reload模式下workers只能为1
环境变量与配置文件混用时的优先级
命令行参数 > 配置文件 > 环境变量。这意味着：
- 如果配置文件里写了
"port": 8000，但命令行又加了--port 9000，最终监听9000 -
UVICORN_PORT环境变量不会覆盖配置文件里的port，除非你根本没传--config - 想让环境变量生效，得删掉配置文件里的对应项，或改用纯环境变量方式（不带
--config）
典型陷阱：Docker部署时，在docker-compose.yml里设了UVICORN_WORKERS=8，又挂载了uvicorn_config.py且里面写了"workers": 4 → 最终还是4，环境变量没起作用。
配置文件里怎么安全读取环境变量
别在配置文件里直接用os.environ.get("PORT")裸调用，否则启动时出错会导致整个服务无法启动。推荐封装默认值和类型转换：
# uvicorn_config.py
import os
<p>def env_int(key: str, default: int) -> int:
try:
return int(os.environ.get(key, default))
except (ValueError, TypeError):
return default</p><p>uvicorn_config = {
"app": "main:app",
"host": os.environ.get("UVICORN_HOST", "0.0.0.0"),
"port": env_int("UVICORN_PORT", 8000),
"workers": env_int("UVICORN_WORKERS", 2),
"log_level": os.environ.get("UVICORN_LOG_LEVEL", "info"),
}</p>
这样既保留了配置文件的可维护性，又支持Docker/K8s通过环境变量动态覆盖，还防了类型错误崩溃。
真正难的不是写配置，而是让不同环境下的配置变更不互相干扰 —— 比如开发机上reload=True必须关掉，而CI流水线里又要校验配置文件语法是否合法。这些边界情况，往往比参数本身更耗时间。
