本文详解如何在 Pydantic CliSubCommand 场景下，为嵌套子命令模型（如 AwsStsGcp）正确注入环境变量，重点解决 BaseSettings 在子命令层级失效、字段被误判为必填的问题。核心方案是启用 env_nested_delimiter 并遵循命名约定。
本文详解如何在 pydantic `clisubcommand` 场景下，为嵌套子命令模型（如 `awsstsgcp`）正确注入环境变量，重点解决 `basesettings` 在子命令层级失效、字段被误判为必填的问题。核心方案是启用 `env_nested_delimiter` 并遵循命名约定。
在使用 Pydantic 构建分层 CLI 应用时，一个常见痛点是：环境变量无法穿透到 CliSubCommand 所包装的子模型中。你可能已确认 .env 文件能被顶层 BaseSettings 读取，但像 aws_access_key 和 aws_secret_key 这类敏感字段，在 AwsStsGcp 作为 CliSubCommand[AwsStsGcp] 被声明时，却始终报错 Field required——即使它们已在 .env 中定义。
根本原因在于：Pydantic CLI 解析器默认不递归解析嵌套模型的环境变量。当 AwsStsGcp 作为 Tool.aws_sts 的子命令被实例化时，其字段不会自动从全局环境（如 AWS_ACCESS_KEY）映射，除非显式启用嵌套解析机制。
✅ 正确解法：启用 env_nested_delimiter 并规范环境变量命名
你需要在 AwsStsGcp 类的 model_config 中启用嵌套环境变量支持，并将环境变量名改为带前缀的层级格式：
# aws_sts_gcp.py
from pydantic import SecretStr, BaseModel, Field
from pydantic_settings import BaseSettings, SettingsConfigDict
class AwsStsGcp(BaseSettings):
# ✅ 关键配置：启用嵌套环境变量解析，使用双下划线作为分隔符
model_config = SettingsConfigDict(
env_file=".env",
env_file_encoding="utf-8",
env_nested_delimiter="__", # ← 必须设置！
extra="ignore"
)
destination_bucket: str
src_bucket: str
manifest_path: str | None = None
aws_access_key: SecretStr = Field(alias="AWS_ACCESS_KEY")
aws_secret_key: SecretStr = Field(alias="AWS_SECRET_KEY")
tranfer_name: str # ⚠️ 注意拼写：应为 transfer_name（建议修正）
project_id: str
def cli_cmd(self) -> None:
from python_tools.gcp.aws_gcs_transfer import create_aws_transfer_job
create_aws_transfer_job(self)
同时，更新你的 .env 文件，按子命令字段路径命名环境变量：
# .env AWS_STS__AWS_ACCESS_KEY=test AWS_STS__AWS_SECRET_KEY=test # 如果还需覆盖其他字段（可选）： AWS_STS__DESTINATION_BUCKET=my-gcs-bucket AWS_STS__SRC_BUCKET=my-aws-bucket
? 命名规则说明：AWS_STS 是 Tool 模型中字段名 aws_sts 的 大写 + 下划线形式；__ 是 env_nested_delimiter 指定的分隔符；AWS_ACCESS_KEY 是 AwsStsGcp 内部字段 aws_access_key 对应的 alias（或字段名转大写下划线）。
? 补充建议：
-
避免混用
BaseModel与BaseSettings：CliSubCommand的目标类应统一继承BaseSettings（而非BaseModel），否则环境变量解析逻辑不生效。你最初尝试的AwsStsGcp(BaseModel)方案天然不支持env_file或env_nested_delimiter。 -
CLI 参数优先级：命令行传入的参数（如
--aws-access-key xxx）会自动覆盖环境变量值，符合预期行为。 -
安全提示：
SecretStr字段在日志/打印中自动脱敏，配合环境变量使用可有效规避密钥硬编码风险。 -
调试技巧：在
AwsStsGcp.cli_cmd()开头添加print(self.model_dump())可验证环境变量是否成功注入。
最终，运行 CLI 时无需额外传参即可加载密钥：
python cli_runner.py aws-sts \ --destination-bucket my-gcs-bucket \ --src-bucket my-aws-bucket \ --project-id my-project \ --tranfer-name sts-job
只要 .env 中存在 AWS_STS__AWS_ACCESS_KEY 和 AWS_STS__AWS_SECRET_KEY，Pydantic 将自动完成绑定，彻底解决“字段必填但未提供”的报错。
