本文详解如何在 Pydantic CliSubCommand 场景下，为嵌套子命令模型（如 AwsStsGcp）正确加载环境变量，重点解决 BaseSettings 在 CLI 子命令中无法自动解析顶层环境变量的问题。
本文详解如何在 pydantic `clisubcommand` 场景下，为嵌套子命令模型（如 `awsstsgcp`）正确加载环境变量，重点解决 `basesettings` 在 cli 子命令中无法自动解析顶层环境变量的问题。
在使用 Pydantic 构建分层 CLI 工具时，一个常见误区是：直接将 BaseSettings 用作 CliSubCommand 的泛型参数，并期望其像独立运行的设置类一样自动读取 .env 文件或全局环境变量。但实际中，当 AwsStsGcp 作为 CliSubCommand[AwsStsGcp] 被嵌套在主 Tool 类中时，Pydantic CLI 解析器不会递归应用 SettingsConfigDict（如 env_file），也不会自动将顶层环境变量映射到子命令字段——除非显式启用嵌套环境变量解析机制。
✅ 正确解法是：启用 env_nested_delimiter 并采用双下划线（__）命名约定声明环境变量。
✅ 步骤一：修改子命令模型，启用嵌套环境变量支持
将 aws_sts_gcp.py 中的 AwsStsGcp 改为继承 BaseSettings（而非 BaseModel），并配置 env_nested_delimiter：
# aws_sts_gcp.py
from pydantic import SecretStr, Field
from pydantic_settings import BaseSettings, SettingsConfigDict
class AwsStsGcp(BaseSettings):
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
# 关键：启用嵌套环境变量解析
model_config = SettingsConfigDict(
env_nested_delimiter='__',
extra='ignore',
)
def cli_cmd(self) -> None:
from python_tools.gcp.aws_gcs_transfer import create_aws_transfer_job
create_aws_transfer_job(self)? 原理说明：
env_nested_delimiter='__'告诉 Pydantic，当该模型作为CliSubCommand被嵌套在父模型（如Tool.aws_sts）中时，应尝试从形如AWS_STS__AWS_ACCESS_KEY的环境变量中提取值，其中AWS_STS对应字段名aws_sts的大写蛇形格式（aws_sts→AWS_STS），__为分隔符，后接字段别名（AWS_ACCESS_KEY）。
✅ 步骤二：按规范命名环境变量
在 .env 文件或系统环境中，必须使用嵌套格式命名变量：
# .env AWS_STS__AWS_ACCESS_KEY="AKIA...XXXX" AWS_STS__AWS_SECRET_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 其他非嵌套字段（如 project_id）若需环境变量，也需同理： AWS_STS__PROJECT_ID="my-gcp-project"
⚠️ 注意：AWS_ACCESS_KEY（无前缀）将被忽略；只有带 AWS_STS__ 前缀的变量才会被 aws_sts 子命令识别。
✅ 步骤三：保持主工具类简洁（无需继承 BaseSettings）
root_tool.py 中的 Tool 类不应继承 BaseSettings，否则会干扰 CLI 参数解析逻辑（尤其与 CliSubCommand 协同时）。推荐保持为纯 BaseModel：
# root_tool.py
from pydantic import BaseModel
from pydantic_settings import CliSubCommand, CliApp
from python_tools.gcp.models.aws_sts_gcp import AwsStsGcp
class DummyCommand(BaseModel):
project_id: str
def cli_cmd(self) -> None:
print(f'This is a dummy command: {self.project_id}')
class Tool(BaseModel):
aws_sts: CliSubCommand[AwsStsGcp]
dummy: CliSubCommand[DummyCommand]
def cli_cmd(self) -> None:
CliApp.run_subcommand(self)✅ 验证与调用方式
确保 CLI 入口正常启动：
# cli_runner.py
from python_tools.gcp.models.root_tool import Tool
from pydantic_settings import CliApp
if __name__ == '__main__':
CliApp.run(Tool)运行命令（环境变量已加载）：
# 无需传参，环境变量自动注入 python cli_runner.py aws-sts \ --destination-bucket my-gcs-bucket \ --src-bucket my-aws-bucket \ --tranfer-name aws-to-gcs \ --project-id my-gcp-project
此时 AwsStsGcp 实例将自动填充 aws_access_key 和 aws_secret_key，无需命令行显式传入，也无需全局配置污染。
⚠️ 注意事项与最佳实践
-
字段别名（
alias）必须与环境变量后缀严格一致：如Field(alias='AWS_ACCESS_KEY')对应AWS_STS__AWS_ACCESS_KEY； -
避免在子命令中重复定义
env_file：.env应由最外层 CLI 控制（或统一由用户加载），子命令仅负责解析已存在的环境变量； -
敏感字段务必使用
SecretStr+.get_secret_value()：防止日志泄露（如示例中aws_gcs_transfer.py的调用方式已正确）； -
拼写校对：
tranfer_name应为transfer_name，建议修正以提升可维护性； -
调试技巧：临时添加
print(self.model_dump())到cli_cmd()中，验证字段是否成功注入。
通过以上配置，你即可在保持 CLI 结构清晰、职责分离的前提下，安全、灵活地为特定子命令注入敏感或可配置的环境变量。
