Pydantic v2 中 BaseSettings 已移至独立包 pydantic-settings，需改用 from pydantic_settings import BaseSettings，并注意环境变量映射、.env 文件路径及 JSON 类型解析等行为变化。
Pydantic v2 里 BaseSettings 已被移除，别再照旧文档抄代码
直接说结论：Pydantic v2（即 pydantic>=2.0）彻底移除了 BaseSettings，它现在是独立包 pydantic-settings。如果你 pip install pydantic 后还 import pydantic.BaseSettings，会报 AttributeError: module 'pydantic' has no attribute 'BaseSettings'。
常见错误现象：
- 项目升级 Pydantic 到 2.x 后配置类突然报错
- 教程里写的
from pydantic import BaseSettings在本地跑不通 - IDE 提示未解析的引用，但安装完
pydantic-settings还是没用——因为没改 import 路径
实操建议：
- 卸载旧依赖：
pip uninstall pydantic（如果混装了 v1 和 v2） - 安装新包：
pip install pydantic-settings - 改 import：
from pydantic_settings import BaseSettings（不是pydantic） - 注意命名空间：v2 的
BaseSettings默认启用case_sensitive=False，环境变量名自动转小写匹配字段（如DB_URL→db_url），和 v1 行为不同
读取 .env 文件时，env_file 路径不生效？检查加载顺序和相对路径基准
BaseSettings 默认不自动读 .env，必须显式传 env_file 参数；而且这个路径是相对于「当前工作目录」（os.getcwd()），不是文件所在目录。
立即学习“Python免费学习笔记（深入）”；
常见错误现象：
- 把
.env放在 settings.py 同级，运行时报FileNotFoundError - 用 IDE Run 按钮执行时能读，命令行
python main.py就读不到 - 设置
env_file=".env"却加载了其他地方的同名文件（比如父目录下的）
实操建议：
- 显式指定绝对路径更可靠：
env_file=Path(__file__).parent / ".env" - 确认当前工作目录：
print(os.getcwd())，尤其在多入口或打包场景下 - 多个 env 文件可叠加：
env_file=[".env", ".env.local"]，后加载的覆盖前一个 - 注意优先级：环境变量 >
env_file> 类字段默认值
字段类型是 list 或 dict，为什么从环境变量解析失败？
环境变量本质是字符串，BaseSettings 不会自动做 JSON 解析。写 ALLOWED_HOSTS='["localhost", "127.0.0.1"]' 不会变成 list，而是原样当 str 存。
使用场景：
- Django 风格的
ALLOWED_HOSTS、INSTALLED_APPS - 需要动态配置的 API 白名单、数据库连接池参数
实操建议：
- 手动解析：字段类型设为
str，用field_validator处理，例如：@field_validator('allowed_hosts', mode='before')<br>def parse_hosts(cls, v):<br> if isinstance(v, str):<br> return json.loads(v)<br> return v - 避免用逗号分隔字符串（如
"a,b,c"）→ 易混淆空格、引号、转义，JSON 更明确 - 嵌套 dict 更推荐用单独的
.env.json或 YAML，而非塞进环境变量
生产环境用 Docker + docker run -e，字段却没被覆盖？查大小写和字段名映射
BaseSettings 默认把字段名转成大写 + 下划线来匹配环境变量，但前提是字段名本身是合法的 Python 变量名（不能含破折号、点号等）。比如 api_url → API_URL，但 api-v1 就无法映射。
常见错误现象：
- Docker 命令里写了
-e DB_HOST=xxx，但程序里db_host还是默认值 - 字段用了
Field(alias="DB_HOST")却没生效 - CI/CD 流水线里环境变量明明存在，
BaseSettings就是读不到
实操建议：
- 字段名必须是蛇形命名（
snake_case），否则不会自动转换 - 想用破折号（如
log-level），得显式声明 alias：log_level: str = Field(alias="LOG_LEVEL") - 调试时打印
settings.model_dump()和os.environ对比，看是否真传进来了 - 容器内执行
env | grep DB，确认变量名拼写、大小写完全一致
最常被忽略的一点：Docker 的 -e 只传单个变量，批量传要用 --env-file，且该文件格式必须是 KEY=VALUE，不能有空格或注释行。
