Python配置加载统一入口_多环境配置管理技巧【技巧】

林译川

2026-10-05 • 👁 0人浏览过

推荐用 pydantic-settings 统一加载配置，自动按环境变量 > 配置文件 > 默认值优先级合并，支持类型校验与 ValidationError 提前报错，避免硬编码或手动读 YAML 导致的覆盖遗漏和上线故障。用

os.environ

pydantic-settings

做配置入口最稳硬编码环境判断或手动读 YAML 文件再拼路径，容易漏覆盖、难测试、上线出错。推荐用

pydantic-settings

（

pydantic

v2+ 官方维护的子包）统一加载，它自动按优先级合并：环境变量 > 配置文件 > 默认值，且带类型校验和错误提示。

settings.py

中定义一个继承

BaseSettings

的类，字段名即配置项名，类型注解即校验规则通过

env_file

参数指定不同环境的

.env

文件，例如

.env.prod

、

.env.dev

环境切换靠

ENVIRONMENT

环境变量控制，不改代码、不重打包启动时若字段缺失或类型不符，会直接抛

ValidationError

，比运行中报

KeyError

更早暴露问题

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    DATABASE_URL: str
    LOG_LEVEL: str = "INFO"
    DEBUG: bool = False

    class Config:
        env_file = f".env.{os.getenv('ENVIRONMENT', 'dev')}"
        case_sensitive = False

避免

.env

文件被 Git 提交的三个实操动作本地开发用

.env.dev

，但里面可能含数据库密码或密钥；CI/CD 里靠环境变量注入，不依赖文件。若没管好，轻则泄露凭证，重则触发安全扫描告警。在

.gitignore

中明确加一行

.env.*

，而不是只写

.env

CI 脚本里用

export ENVIRONMENT=prod

，再让

pydantic-settings

自动加载

.env.prod

—— 但该文件本身不进仓库，由运维单独分发或注入本地调试时，用

python -m pip install python-dotenv

并确保

pydantic-settings

的

env_file_encoding

设为

"utf-8"

，否则中文注释或值会乱码多环境配置继承与覆盖的真实写法不是所有配置都要每环境写一遍。

pydantic-settings

不支持 YAML 的

!include

，但可以用 Python 层级继承模拟“基础配置 + 环境补丁”。建

settings_base.py

，定义公共字段如

APP_NAME

、

TIMEZONE

各环境 settings 类（如

DevSettings

、

ProdSettings

）继承它，并只重写差异字段，比如

DEBUG = True

或

DATABASE_URL

最终实例化时用

Settings()

即可，无需手动选类 —— 因为

env_file

已由

ENVIRONMENT

决定注意：字段默认值在基类里设，子类里不要重复设，否则会覆盖基类逻辑

os.getenv('ENVIRONMENT')

没生效？检查这三点常见现象：本地跑是

dev

，部署后还是读

.env.dev

，日志里

DATABASE_URL

明明配了却没生效。 Python 3.14.3 微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。下载立即学习 “ Python免费学习笔记（深入） ”；确认启动命令是否真正设置了环境变量，比如

ENVIRONMENT=prod python main.py

，而不是

export ENVIRONMENT=prod && python main.py

（后者在某些 shell 下不生效）检查是否在

import settings

之前就调用了

os.getenv('ENVIRONMENT')

——

pydantic-settings

初始化时才读，但你提前读可能拿到

None

Docker 镜像里要显式传参：

docker run -e ENVIRONMENT=prod myapp

，不能只写

ENV ENVIRONMENT prod

（构建时固定，无法运行时覆盖）配置加载看似简单，但环境变量优先级、文件编码、Git 忽略粒度、Docker 启动参数这四点一旦错一个，就可能导致预发和线上行为不一致。建议把

Settings()

实例化放在应用入口最上方，加一行

print(f"Loaded env: {settings.ENVIRONMENT}")

快速验证。

相关文章