如何正确使用Pydantic Settings加载环境变量？

Question

在使用 Pydantic 的 `BaseSettings` 类加载环境变量时，开发者常遇到的一个问题是：为何在 `.env` 文件中定义的环境变量未被正确加载？ 通常，这是由于未正确配置 `Settings` 类的 `Config` 子类，或未指定 `.env` 文件路径所致。 此外，变量名大小写不一致、字段类型不匹配或未使用 `python-dotenv` 包支持，也会导致加载失败。 本文将演示如何通过配置 `env_file` 参数、使用 `Config` 类设置环境前缀和区分大小写，以及结合 `python-dotenv` 实现正确加载环境变量的最佳实践。

Answer 1

一、Pydantic BaseSettings 加载环境变量常见问题解析

在使用 Pydantic 的 BaseSettings 类加载环境变量时，开发者常常遇到环境变量未被正确加载的问题。这通常与配置方式、文件路径、命名规范及依赖缺失等有关。

1.1 未正确配置 Config 子类

Pydantic 的 BaseSettings 允许通过内部的 Config 类进行自定义配置。例如：

class Settings(BaseSettings):
    app_name: str
    debug_mode: bool

    class Config:
        env_file = '.env'
        env_prefix = 'APP_'
    

若未正确设置 env_file 或 env_prefix，可能导致环境变量无法正确识别。

1.2 未指定 .env 文件路径

默认情况下，Pydantic 不会自动查找 .env 文件。开发者需通过 env_file 参数指定文件路径：

class Config:
    env_file = './config/.env'
    

路径错误或文件不存在会导致加载失败。

1.3 环境变量名大小写不一致

Pydantic 默认将字段名转换为大写来匹配环境变量。例如，字段 debug_mode 会匹配 DEBUG_MODE。

若设置了 env_prefix，则应使用前缀加字段名大写形式：

APP_DEBUG_MODE=True
    

1.4 字段类型不匹配

字段类型不匹配可能导致解析失败。例如：

class Settings(BaseSettings):
    port: int

# .env 文件内容：
PORT=abcd
    

此时会抛出类型转换错误。

1.5 未使用 python-dotenv 包

Pydantic 依赖 python-dotenv 来加载 .env 文件。若未安装该包：

pip install python-dotenv

则无法读取 .env 文件中的变量。

二、解决方案与最佳实践

为了确保环境变量能被正确加载，开发者应遵循以下最佳实践：

2.1 正确配置 Config 子类

建议显式定义 env_file 和 env_prefix：

class Settings(BaseSettings):
    app_name: str
    debug_mode: bool

    class Config:
        env_file = '.env'
        env_prefix = 'MYAPP_'
    

2.2 使用 python-dotenv 支持

确保已安装 python-dotenv：

pip install python-dotenv

这样，Pydantic 会自动读取 .env 文件中的变量。

2.3 遵循命名规范

字段名应与环境变量名匹配（大写 + 下划线）：

字段名	环境变量名
app_name	APP_NAME
debug_mode	DEBUG_MODE

2.4 启用区分大小写支持

可以通过设置 case_sensitive = True 来启用环境变量大小写敏感：

class Config:
    env_file = '.env'
    case_sensitive = True
    

此时变量名必须完全匹配。

2.5 调试与验证机制

可通过打印设置实例来验证是否加载成功：

settings = Settings()
print(settings.dict())
    

也可以使用日志或断言来增强调试能力。

三、流程图：BaseSettings 加载机制

graph TD
    A[开始] --> B[创建 Settings 实例]
    B --> C[读取 Config.env_file]
    C --> D{是否存在 python-dotenv?}
    D -- 是 --> E[加载 .env 文件]
    D -- 否 --> F[跳过加载]
    E --> G[匹配字段名与环境变量]
    G --> H{是否匹配成功?}
    H -- 是 --> I[赋值字段]
    H -- 否 --> J[抛出错误或使用默认值]
    I --> K[返回 Settings 实例]
    J --> K
    F --> G