FastAPI 环境变量实战指南:用 pydantic-settings 管理配置、.env 文件与依赖注入

原创2026-10-10 21:23:041,422 阅读
文章标签:后端Web框架API设计异步编程认证鉴权

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 及其生态一致的约定。好在 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()

这里有几个关键行为:

  1. 大小写不敏感读取:实例化 Settings() 时,Pydantic 会以不区分大小写的方式读取环境变量。因此大写变量 APP_NAME 会正确映射到属性 app_name。
  2. 类型转换与校验:数据会被转换并校验。只要声明了 items_per_user: int,即使环境变量里是字符串 "50",settings.items_per_user 也是 int 类型。
  3. 必填字段: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 为模板补齐测试。

登录后查看全文
fastapi