使用pydantic-settings带别名时，如何让初始化参数优先于环境变量？

问题描述 #

使用Pydantic v2的pydantic-settings从环境变量加载配置时，通过Field(alias=...)绑定环境变量后，构造函数传入的初始化参数被环境变量覆盖，且传入不符合类型要求的值时不触发验证。调整extra="allow"后，初始化参数虽生效，但字段类型验证失效。

复现代码 #

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

class MySettings(BaseSettings):
    api_key: StrictStr = Field(..., alias="TEST_API_KEY")
    aws_region: StrictStr = Field(..., alias="AWS_REGION")

    model_config = SettingsConfigDict(extra="ignore", populate_by_name=True)

# .env 文件内容
# TEST_API_KEY="TEST_API_KEY_VALUE"
# AWS_REGION="us-east-1"

# 测试输出
print(MySettings().model_dump())
# 预期: {'api_key': 'TEST_API_KEY_VALUE', 'aws_region': 'us-east-1'}

print(MySettings(api_key="ANOTHER_API_KEY_TO_OVERRIDE").model_dump())
# 预期: {'api_key': 'ANOTHER_API_KEY_TO_OVERRIDE', 'aws_region': 'us-east-1'}
# 实际: {'api_key': 'TEST_API_KEY_VALUE', 'aws_region': 'us-east-1'}

print(MySettings(api_key=111).model_dump())
# 预期: 触发ValidationError
# 实际: {'api_key': 'TEST_API_KEY_VALUE', 'aws_region': 'us-east-1'}

补充现象 #

当设置extra="allow"时，初始化参数生效但类型验证失效：

print(MySettings(api_key=111).model_dump())
# 输出: {'api_key': 111, 'aws_region': 'us-east-1'}

解决方案 #

方法1：自定义配置源优先级 #

通过settings_customise_sources方法明确配置源顺序，确保构造函数参数优先级最高：

from pydantic import Field, StrictStr
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic_settings.sources import InitSettingsSource, EnvSettingsSource, DotEnvSettingsSource

class MySettings(BaseSettings):
    api_key: StrictStr = Field(..., alias="TEST_API_KEY")
    aws_region: StrictStr = Field(..., alias="AWS_REGION")

    model_config = SettingsConfigDict(extra="ignore", populate_by_name=True)

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls,
        init_settings,
        env_settings,
        dotenv_settings,
        file_secret_settings,
    ):
        # 指定优先级：构造参数 > 环境变量 > .env文件
        return (
            init_settings,
            env_settings,
            dotenv_settings,
            file_secret_settings,
        )

测试后可得到预期结果：

• 无构造参数时，读取环境变量值
• 传入构造参数时，覆盖环境变量值
• 传入不符合类型的值时，触发ValidationError

方法2：移除populate_by_name=True #

如果不需要通过字段名的大写形式读取环境变量，可移除该配置，避免参数匹配逻辑冲突：

class MySettings(BaseSettings):
    api_key: StrictStr = Field(..., alias="TEST_API_KEY")
    aws_region: StrictStr = Field(..., alias="AWS_REGION")

    model_config = SettingsConfigDict(extra="ignore")

原理说明 #

默认情况下pydantic-settings的优先级应为构造参数 > 环境变量 > .env文件，但在使用alias且开启populate_by_name=True时，可能出现参数匹配逻辑冲突，导致构造参数被误判为额外字段并忽略。通过自定义配置源顺序，可确保构造参数的优先级，同时保留字段的类型验证能力。

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