CodeWalk

pydantic-settings：Pydantic V2配置管理最佳实践

作者：我还是少年 · 2026-05-30 12:55

pydantic-settings是Pydantic V2中的配置管理库，可同时从环境变量、.env文件、YAML文件等多源加载配置。请介绍pydantic-settings的核心用法（BaseSettings模型、Field验证、SettingsConfigDict配置），以及它在类型安全和验证方面的优势。

回答

我还是少年

pydantic-settings基础用法

from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field, RedisDsn

class Settings(BaseSettings):
    # 类型注解自动类型转换和验证
    app_name: str = Field(default='myapp', alias='APP_NAME')
    debug: bool = False
    database_url: str
    redis_dsn: RedisDsn  # 自动URL验证
    max_connections: int = Field(default=10, ge=1, le=100)

    model_config = SettingsConfigDict(
        env_file='.env',          # 加载.env文件
        env_file_encoding='utf-8',
        env_prefix='MYAPP_',      # 环境变量前缀
        extra='ignore',           # 忽略额外字段
        case_sensitive=False,     # 大小写不敏感
    )

settings = Settings()
# 自动从环境变量或.env文件读取

多源加载优先级

pydantic-settings的优先级（从高到低）：

  1. 初始化时传入的参数：Settings(database_url='...')
  2. 系统环境变量（os.environ）
  3. env_file参数指定的.env文件
  4. 模型字段的默认值

嵌套配置

class DatabaseConfig(BaseModel):
    host: str = 'localhost'
    port: int = 5432

class Settings(BaseSettings):
    database: DatabaseConfig
    # 环境变量需要: MYAPP_DATABASE_HOST='prod.example.com'

相比传统方案的突出优势

功能configparser/tomllibpydantic-settings
类型自动转换手动转换自动（str→bool/int/URL等）
验证规则无Field(ge=, le=, regex=)
环境变量需手动读取自动注入
.env文件需python-dotenv内置支持
嵌套配置不支持支持
IDE补全支持差（字符串访问）好（属性访问+类型提示）

最佳实践：新项目推荐使用pydantic-settings替代环境变量+configparser的组合。