如何让环境变量优先覆盖Pydantic Settings模型中的配置值？

你遇到的核心问题是加载YAML的方式破坏了Pydantic Settings默认的优先级逻辑。Pydantic Settings本身就支持「环境变量 > 配置文件 > 默认值」的优先级，但前提是得用官方推荐的方式加载配置文件，不能手动读YAML后覆盖设置。

正确实现方式 #

1. 标准配置：让BaseSettings自动处理文件与环境变量 #

直接用BaseSettings的model_config指定YAML文件路径，同时绑定对应的环境变量：

from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field

class AppSettings(BaseSettings):
    foo: int = Field(10, env="APP_FOO")  # 绑定环境变量APP_FOO

    model_config = SettingsConfigDict(
        yaml_file="config.yaml",  # 指定你的YAML配置文件路径
        env_prefix="APP_"  # 可选，给所有环境变量加统一前缀，避免冲突
    )

# 测试：先设置环境变量
import os
os.environ["APP_FOO"] = "20"

# 初始化配置
settings = AppSettings()

# 断言会通过，环境变量值20优先于YAML里的13
assert settings.foo == 20

2. 别用这种错误写法 #

如果你之前是手动读YAML再传入Settings构造函数，这种操作会直接覆盖环境变量的优先级，比如：

# ❌ 错误示例：手动加载YAML会把环境变量的值冲掉
import yaml
with open("config.yaml") as f:
    yaml_data = yaml.safe_load(f)

settings = AppSettings(**yaml_data)  # YAML里的foo=13会覆盖环境变量的20

这种写法相当于把YAML数据作为初始化参数，优先级比环境变量还高，所以绝对不能这么干。

3. 自定义优先级（可选） #

如果需要更灵活的来源顺序，可以手动调整配置来源的优先级：

from pydantic_settings import BaseSettings
from pydantic_settings.sources import YamlConfigSource, EnvSettingsSource

class AppSettings(BaseSettings):
    foo: int = 10

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls,
        init_settings,
        env_settings,
        dotenv_settings,
        file_secret_settings,
    ):
        # 明确指定顺序：环境变量先生效，然后是YAML，最后是默认值
        return (
            env_settings,
            YamlConfigSource(settings_cls, yaml_file="config.yaml"),
            init_settings,
        )

settings = AppSettings()

关键注意点 #

• 环境变量名称要和字段的env参数对应，或者用env_prefix统一管理前缀
• 绝对不要手动把YAML内容传入Settings构造函数，让BaseSettings自动处理文件加载
• 自定义优先级时，确保env_settings排在YAML来源的前面

内容的提问来源于stack exchange，提问作者superstator