FastAPI 环境变量实战指南:用 pydantic-settings 管理配置、.env 文件与依赖注入
FastAPI 环境变量实战指南:用 pydantic-settings 管理配置、.env 文件与依赖注入
环境变量是 FastAPI 应用读取外部配置(数据库 URL、邮件凭据、密钥等)的标准方式。本指南以官方文档 环境变量 及其进阶篇 Einstellungen und Umgebungsvariablen(设置与环境变量) 为骨架,结合本仓库 docs_src/settings 的完整示例与 tests/test_tutorial/test_settings 的测试用例,讲解从"读取一个环境变量"到"用 pydantic-settings 构建可测试的配置体系"的完整路径。读完你将在 FastAPI 项目中落地一套支持类型校验、.env 文件、依赖注入与测试覆盖的配置管理方案。
环境变量:独立于 Python 代码的配置载体
环境变量(environment variable,简称 env var) 是存在于操作系统中的值,位于 Python 代码之外,可被你的应用以及其他任何程序读取。在 FastAPI 项目中,它们常被用于承载以下配置:
- 数据库连接 URL(如
DATABASE_URL); - 邮件服务的凭据(如
SMTP_USER、SMTP_PASSWORD); - 密钥(secret keys),例如 JWT 签名密钥、
SECRET_KEY。
为什么不用硬编码?因为这些配置可变(数据库地址会随环境切换)且很多属于敏感信息(密钥不应进入版本库)。环境变量天然满足这两点:按运行环境注入、不落盘于源码。
类型与验证:环境变量只有字符串
环境变量位于 Python 之外,必须与其他程序、整个系统(以及 Linux、Windows、macOS 等不同操作系统)兼容,因此只能承载文本字符串。这意味着:
- 在 Python 中通过
os.getenv(...)或os.environ读取到的任何值都是str; - 任何到其他类型(
int、bool、URL等)的转换与校验都必须由代码完成。
以本仓库源码为例,FastAPI 自身在多个位置直接读取环境变量,全部按字符串处理:
- fastapi/routing.py#L1931 中通过
os.environ.get("FASTAPI_ENV") != "development"判断是否为开发环境; - fastapi/applications.py#L1041 通过
os.getenv("FASTAPI_OTEL_AUTO_CONFIGURE", "").lower()读取遥测自动配置开关; - fastapi/telemetry/_runtime.py 中
OTEL_EXPORTER_OTLP_*系列变量的读取同样返回字符串后再做.strip().lower()处理。
可见"读出来是字符串、转换交给代码"是 FastAPI 及其生态一致的约定。好在 pydantic-settings 把这个约定变成了声明式的一行代码。
安装 pydantic-settings
Pydantic 提供了处理环境变量的利器 BaseSettings。按官方文档,用 uv 将其加入项目:
$ uv add pydantic-settings
---> 100%
或者直接安装 FastAPI 的 all 扩展:
$ uv add "fastapi[all]"
---> 100%
仓库的 pyproject.toml#L81 印证了这一点:standard、standard-no-fastapi-cloud-cli 与 all 三组可选依赖中都声明了 "pydantic-settings >=2.0.0",所以安装 fastapi[all] 后无需再单独添加。
创建 Settings 对象:声明即配置
参考 docs_src/settings/tutorial001_py310.py,导入 BaseSettings 并创建子类,方式与声明 Pydantic 模型几乎相同——用类型注解声明类属性,并给出默认值:
from fastapi import FastAPI
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
app_name: str = "Awesome API"
admin_email: str
items_per_user: int = 50
settings = Settings()
app = FastAPI()
这里有几个关键行为:
- 大小写不敏感读取:实例化
Settings()时,Pydantic 会以不区分大小写的方式读取环境变量。因此大写变量APP_NAME会正确映射到属性app_name。 - 类型转换与校验:数据会被转换并校验。只要声明了
items_per_user: int,即使环境变量里是字符串"50",settings.items_per_user也是int类型。 - 必填字段:
admin_email: str没有默认值,属于必填项。若环境变量缺失,实例化时会抛出ValidationError。
仓库测试 tests/test_tutorial/test_settings/test_tutorial001.py 验证了这些行为:测试通过 monkeypatch.setenv("ADMIN_EMAIL", "admin@example.com") 注入变量后请求 /info,断言 app_name 取默认值 "Awesome API"、items_per_user 为 50;配套的 tests/test_tutorial/test_settings/test_app01.py#L31-L46 则在删除 ADMIN_EMAIL 环境变量后断言导入模块会抛出 ValidationError,错误定位到 ("admin_email",)、类型为 missing。
你还可以复用 Pydantic 模型的全部校验工具,例如不同的数据类型以及 Field() 的额外校验。
在应用中使用 settings 对象
实例化后的 settings 对象可直接用于路径操作函数:
@app.get("/info")
async def info():
return {
"app_name": settings.app_name,
"admin_email": settings.admin_email,
"items_per_user": settings.items_per_user,
}
运行服务器并注入环境变量
启动服务器时把配置作为环境变量传入,例如同时设置 ADMIN_EMAIL 和 APP_NAME:
Linux、macOS、Windows Bash:
$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Bash 中为单个命令设置多个环境变量时,用空格分隔,并全部放在命令之前。
Windows PowerShell:
$ $Env:ADMIN_EMAIL = "deadpool@example.com"
$ $Env:APP_NAME = "ChimichangApp"
$ uv run fastapi run main.py
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
运行结果:
admin_email为"deadpool@example.com";app_name为"ChimichangApp";items_per_user保留默认值50。
把设置放到独立模块
按照 Bigger Applications - Multiple Files 的多文件组织方式,可以把设置抽到 config.py(见 docs_src/settings/app01_py310/config.py):
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
app_name: str = "Awesome API"
admin_email: str
items_per_user: int = 50
settings = Settings()
然后在 main.py 中引用(见 docs_src/settings/app01_py310/main.py):
from fastapi import FastAPI
from .config import settings
app = FastAPI()
@app.get("/info")
async def info():
return {
"app_name": settings.app_name,
"admin_email": settings.admin_email,
"items_per_user": settings.items_per_user,
}
注意目录中需要存在 __init__.py(本仓库 docs_src/settings/app01_py310/init.py 即为空文件),才能作为包导入。
通过依赖注入提供设置:让测试变简单
全局 settings 对象简单直接,但在测试时不易替换。更优的做法是通过依赖注入提供设置——因为 FastAPI 的 app.dependency_overrides 可以轻松覆盖任何依赖。
配置文件:只声明类,不创建实例
把 docs_src/settings/app02_an_py310/config.py 改为只声明 Settings 类:
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
app_name: str = "Awesome API"
admin_email: str
items_per_user: int = 50
注意这里不再创建 settings = Settings() 默认实例。
主应用:用依赖函数返回 Settings
在 docs_src/settings/app02_an_py310/main.py 中,用 get_settings() 作为依赖:
from functools import lru_cache
from typing import Annotated
from fastapi import Depends, FastAPI
from .config import Settings
app = FastAPI()
@lru_cache
def get_settings():
return Settings()
@app.get("/info")
async def info(settings: Annotated[Settings, Depends(get_settings)]):
return {
"app_name": settings.app_name,
"admin_email": settings.admin_email,
"items_per_user": settings.items_per_user,
}
@lru_cache 的用途稍后详解,现在可以先把它当作一个普通函数。
测试:覆盖依赖即可替换配置
依赖注入的最大收益在测试时体现。参考 docs_src/settings/app02_an_py310/test_main.py:
from fastapi.testclient import TestClient
from .config import Settings
from .main import app, get_settings
client = TestClient(app)
def get_settings_override():
return Settings(admin_email="testing_admin@example.com")
app.dependency_overrides[get_settings] = get_settings_override
def test_app():
response = client.get("/info")
data = response.json()
assert data == {
"app_name": "Awesome API",
"admin_email": "testing_admin@example.com",
"items_per_user": 50,
}
在覆盖函数中,创建新的 Settings(admin_email="testing_admin@example.com") 并返回该对象。FastAPI 处理 /info 请求时就会注入这个测试专用的设置。仓库测试 tests/test_tutorial/test_settings/test_app02.py 同时参数化验证了 app02_py310(经典 Depends 写法)与 app02_an_py310(Annotated 写法)两个变体,两种写法等价。
读取 .env 文件(dotenv)
当设置项很多、且在不同环境频繁变化时,把它们写进文件再按环境变量读取会更方便。这类文件通常命名为 .env,这种实践被称为 dotenv。
以点(
.)开头的文件在 Unix 系系统(Linux、macOS)中是隐藏文件。但 dotenv 文件并不一定非要叫这个名字,文件名可自定义。
安装 python-dotenv
Pydantic 借助外部库 python-dotenv 读取此类文件:
$ uv add python-dotenv
编写 .env 文件
ADMIN_EMAIL="deadpool@example.com"
APP_NAME="ChimichangApp"
在 Settings 中声明 env_file
更新 config.py,参考 docs_src/settings/app03_an_py310/config.py:
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
app_name: str = "Awesome API"
admin_email: str
items_per_user: int = 50
model_config = SettingsConfigDict(env_file=".env")
model_config 专用于 Pydantic 配置。这里通过 SettingsConfigDict(env_file=".env") 指定要读取的 dotenv 文件路径。此后实例化 Settings() 时,.env 中的键值对会被当作环境变量读取、转换并校验。
用 lru_cache 让 Settings 只创建一次
从磁盘读取文件是相对昂贵(慢)的操作,理应只执行一次,而不是每个请求都读。但每次执行 Settings() 都会创建新对象、重新读取 .env。若依赖函数写成:
def get_settings():
return Settings()
那么每个请求都会创建新对象并重新读盘。⚠️ 而加上 @lru_cache 装饰器后,Settings 对象只在首次调用时创建一次。✔️
lru_cache 的技术细节
@lru_cache 会改造被装饰的函数,使其在首次调用后返回缓存的值,而不是每次都重新执行函数体。底层函数对每一组参数组合只执行一次,之后只要以完全相同的一组参数调用,就复用该组合的返回值。例如:
@lru_cache
def say_hi(name: str, salutation: str = "Ms."):
return f"Hello {salutation} {name}"
其执行时序为:say_hi(name="Camila") 首次执行函数体并返回结果;再次以相同参数调用时直接返回存储的结果;say_hi(name="Rick")、say_hi(name="Rick", salutation="Mr.") 则是新的参数组合,各自重新执行;此后同样的组合再次调用时全部命中缓存。
回到我们的依赖 get_settings():它不接收任何参数,因此总是返回同一个值。这使它在行为上几乎等价于一个全局变量——但因为它是一个依赖函数,测试时依然可以通过 app.dependency_overrides[get_settings] 轻松替换。
@lru_cache 来自 functools,是 Python 标准库的一部分,无需额外安装。
FastAPI 自身如何使用环境变量
FastAPI 的源码本身就是"环境变量驱动配置"的活例子,可作为设计参考:
FASTAPI_ENV:在 fastapi/routing.py#L1931 中,os.environ.get("FASTAPI_ENV") != "development"控制前端静态资源目录的自动检查行为——非开发环境下默认检查目录是否存在,开发环境下则跳过检查并给出警告。FASTAPI_OTEL_AUTO_CONFIGURE:在 fastapi/applications.py#L1041 中用于遥测(OpenTelemetry)自动配置的开关,读取后转为小写字符串。OTEL_*系列:在 fastapi/telemetry/_runtime.py 中,导出器、端点、协议等遥测配置全部通过os.getenv读取,并配合or表达式与.strip().lower()实现默认值与规范化。
这些实现印证了本文的核心原则:环境变量永远是字符串,读取、转换、默认值处理都在代码中完成。
总结
借助 Pydantic Settings,你可以在拥有 Pydantic 模型全部能力的前提下管理应用的配置:
- 用依赖注入提供设置,可显著简化测试(通过
dependency_overrides一键替换); - 支持
.env(dotenv)文件,便于按环境切换配置; - 配合
@lru_cache,避免每个请求都重复读取 dotenv 文件,同时保留测试期覆盖能力。
从 os.getenv 读到 BaseSettings 声明式配置,再到依赖注入与缓存,这正是 FastAPI 生态中管理数据库 URL、邮件凭据与密钥等外部配置的推荐路线。你可以基于本仓库的 docs_src/settings 六个示例直接改造自己的项目,并以 tests/test_tutorial/test_settings 为模板补齐测试。