Uvicorn的--config-file参数必须指定有效Python/TOML/YAML配置文件路径，推荐使用Python文件（如uvicorn_config.py），其中定义硬编码变量uvicorn_config字典，键名对应命令行参数（驼峰转下划线），且需确保模块可导入。
uvicorn --config-file 参数必须配合配置文件使用
直接执行 uvicorn main:app --config-file 会报错，因为该参数要求后面必须跟一个有效的 Python 或 TOML/YAML 配置文件路径。Uvicorn 不会自动查找默认配置文件，也不会 fallback 到环境变量或当前目录下某个固定文件名。
配置文件本质是把命令行参数“搬进代码里”，但加载时机更早、优先级更高（高于环境变量，低于命令行参数本身）。
常见错误现象：ConfigError: No configuration file found at 'uvicorn_config.py' —— 实际是路径不对，不是文件名不对；ImportError: cannot import name 'uvicorn_config' —— 文件里用了 from xxx import xxx，但模块没在 PYTHONPATH 中。
- 配置文件必须是可 import 的 Python 模块（推荐），或
.toml/.yaml格式（需额外依赖） - Python 配置文件名随意，但必须确保它能被 Python 解释器 import（即所在目录在
PYTHONPATH或当前工作目录） - 启动时用绝对路径或相对路径均可，但推荐用相对路径（如
--config-file config/uvicorn.py），避免 Docker 或 CI 环境中路径漂移
Python 配置文件怎么写才不报错
最稳妥的方式是只定义一个名为 uvicorn_config 的字典变量，键名与命令行参数一一对应（去掉双横线和短横，驼峰转下划线），Uvicorn 会自动识别并展开。
示例 uvicorn_config.py：
import os
uvicorn_config = {
"app": "main:app",
"host": os.getenv("HOST", "0.0.0.0"),
"port": int(os.getenv("PORT", "8000")),
"workers": int(os.getenv("WORKERS", "2")),
"reload": os.getenv("RELOAD", "false").lower() == "true",
"log_level": "info",
"access_log": True,
"timeout_keep_alive": 5,
}
注意：uvicorn_config 是硬编码变量名，不能改成 CONFIG 或 settings；"app" 键值仍需保持 module:var 格式，不能写成 app = FastAPI() 这样的表达式。
- 不要在配置文件里调用
uvicorn.run()，否则启动时会重复执行 - 避免在配置文件中做耗时操作（如读取大文件、连接数据库），它会在每次 reload 时重新 import
- 如果用了
--reload，配置文件里的workers会被忽略（Uvicorn 强制设为 1），但其他字段仍生效
为什么不用 TOML/YAML 而选 Python 文件
Python 配置文件天然支持环境变量解析、类型转换、条件逻辑，而 TOML/YAML 必须靠额外库（如 PyYAML）且不支持运行时计算。
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
比如想让开发环境自动启用 reload，生产环境禁用：Python 文件里可以写 "reload": os.getenv("ENV") == "dev"；TOML 里只能写死 reload = true，还得靠外部脚本替换。
另一个关键点：PyYAML 默认不安装，pip install uvicorn 不会带它；若用 --config-file config.yaml 却没装 PyYAML，会报 ValueError: Unsupported logging config format，而非清晰的 “missing dependency” 提示。
- Python 配置文件无需额外依赖，兼容性最强
- TOML 支持基础类型，但无法处理
os.getenv()或lambda等动态逻辑 - YAML 更易读，但缩进敏感，CI 流水线中容易因空格问题导致静默失败
启动命令和工作目录必须匹配
执行 uvicorn main:app --config-file config/uvicorn.py 时，Uvicorn 先尝试 import config.uvicorn，这意味着：
— 如果项目结构是 src/main.py + src/config/uvicorn.py，你得先确保 src/ 在 PYTHONPATH 中，或在 src/ 目录下运行命令；
— 如果你在项目根目录运行，但配置文件放在 conf/uvicorn.py，就得加 --app-dir . 或提前设置 PYTHONPATH=.。
- 最简实践：把
uvicorn_config.py放在项目根目录，和main.py同级，然后从该目录执行uvicorn main:app --config-file uvicorn_config.py - 别依赖相对导入，
from config import uvicorn_config容易因工作目录变化失效 - Docker 中务必用
COPY . /app+WORKDIR /app，再执行命令，否则--config-file找不到文件
配置文件启动看似简单，但真正卡住人的往往不是语法，而是 Python 模块导入路径和工作目录之间的隐式耦合。一旦出问题，日志里不会告诉你“找不到配置文件”，只会抛出模糊的 ImportError 或 KeyError: 'app' —— 此时先检查 python -c "import config.uvicorn" 是否成功，比反复改参数更有效。
