使用pydantic-settings时，如何在不修改环境变量名的前提下将扁平环境变量正确映射到嵌套Pydantic模型

我完全理解你遇到的问题——因为设置了env_nested_delimiter="_"，Pydantic会把环境变量里的下划线当成嵌套层级的分隔符，导致PREFIX_S3_BUCKET_NAME被错误解析为s3.bucket.name的嵌套路径，而你的S3Settings模型里只有bucket_name这个字段，所以解析失败后只能 fallback 到YAML的默认值。

下面给你两种实用的解决方案，都不需要修改环境变量名：

方法一：给字段设置别名（简单直接，适合单个字段场景） #

你可以给S3Settings里的bucket_name字段设置一个别名，对应解析后的错误嵌套路径bucket.name，这样Pydantic就能把解析出来的值正确映射到目标字段上：

from pydantic import BaseModel, Field

class S3Settings(BaseModel):
    bucket_name: str = Field(alias="bucket.name")

    class Config:
        allow_population_by_field_name = True

原理说明： #

1. EnvSettingsSource会把PREFIX_S3_BUCKET_NAME解析为s3.bucket.name的嵌套路径
2. 因为bucket_name字段的别名是bucket.name，且allow_population_by_field_name=True允许通过别名赋值
3. 所以解析出来的s3.bucket.name值会被正确赋值给bucket_name字段，覆盖YAML里的默认值

方法二：自定义EnvSettingsSource（通用方案，适合多字段场景） #

如果你有多个嵌套模型的字段名包含下划线，一个个加别名太繁琐，可以自定义EnvSettingsSource的子类，重写解析逻辑，让它优先匹配完整的字段名，而不是盲目拆分下划线：

from pydantic_settings import EnvSettingsSource, PydanticBaseSettingsSource
from pydantic import BaseModel
from typing import Dict, List, Any, Type

class CustomEnvSettingsSource(EnvSettingsSource):
    def _split_env_var_name(self, env_name: str) -> List[str]:
        # 去掉前缀并统一大小写
        if env_name.startswith(self.env_prefix):
            env_name = env_name[len(self.env_prefix):]
        if not self.case_sensitive:
            env_name = env_name.lower()
        
        parts = env_name.split(self.env_nested_delimiter)
        current_model = self.settings_cls
        new_parts = []

        for i, part in enumerate(parts):
            new_parts.append(part)
            
            # 定位当前层级的模型
            if i == 0:
                field = current_model.__fields__.get(part)
            else:
                parent_field = current_model.__fields__.get(new_parts[i-1])
                if parent_field and issubclass(parent_field.type_, BaseModel):
                    current_model = parent_field.type_
                    field = current_model.__fields__.get(part)
                else:
                    field = None
            
            # 检查剩余部分是否是当前模型的完整字段名
            remaining_parts = parts[i:]
            remaining_field_name = self.env_nested_delimiter.join(remaining_parts)
            if not self.case_sensitive:
                remaining_field_name = remaining_field_name.lower()
            
            if remaining_field_name in current_model.__fields__:
                # 剩余部分是完整字段名，停止拆分，合并为一个部分
                new_parts = parts[:i] + [remaining_field_name]
                break
        
        return new_parts

    def parse_env_vars(self, env_vars: Dict[str, Any]) -> Dict[str, Any]:
        parsed: Dict[str, Any] = {}
        for env_name, env_value in env_vars.items():
            if not env_name.startswith(self.env_prefix):
                continue
            
            parts = self._split_env_var_name(env_name)
            current = parsed
            # 构建嵌套字典路径
            for part in parts[:-1]:
                if part not in current:
                    current[part] = {}
                current = current[part]
            
            # 处理字段值
            field_name = parts[-1]
            if not self.case_sensitive:
                field_name = field_name.lower()
            current[field_name] = self._parse_env_var_value(env_value, field_name)
        
        return parsed

然后在Settings类的settings_customise_sources里替换为这个自定义源：

class Settings(BaseSettings):
    mongodb: DatabaseSettings
    s3: S3Settings

    @classmethod
    def settings_customise_sources(
            cls, settings_cls: Type[BaseSettings], **kwargs
    ) -> Tuple[PydanticBaseSettingsSource, ...]:
        return (
            CustomEnvSettingsSource(
                settings_cls,
                env_nested_delimiter="_",
                case_sensitive=False,
                env_prefix="PREFIX_"
            ),
            YamlConfigSettingsSource(settings_cls, yaml_file="config.yaml"),
        )

原理说明： #

1. 解析环境变量名时，会逐步检查当前层级的模型是否存在剩余部分拼接成的完整字段名
2. 比如解析S3_BUCKET_NAME时，在s3层级会发现bucket_name是S3Settings的合法字段，就会直接把s3和bucket_name作为完整路径，而不是拆分成s3.bucket.name
3. 这样就能正确映射到对应的字段，覆盖YAML配置

验证效果 #

修改后运行代码，输出应该会变成：

PREFIX_MONGODB_HOST is set to: localhost
PREFIX_S3_BUCKET_NAME is set to: some-bucket
{'mongodb': {'host': 'localhost', 'port': 27017, 'username': 'USER', 'password': '123456', 'name': 'db', 'collection': 'tasks'}, 's3': {'bucket_name': 'some-bucket'}}

这样就完美解决了你的问题，既不用修改环境变量名，又能正确映射嵌套模型的字段。

备注：内容来源于stack exchange，提问作者Dekel tsairi