cleanenv 不支持自动探测格式，仅通过文件后缀识别解析器：.yaml/.yml→YAML、.json→JSON、.toml→TOML；无后缀或错误后缀将静默失败或panic，且不解析内容；ReadEnv与ReadConfig需手动控制加载顺序与覆盖逻辑。
cleanenv 不支持“自动探测格式”——它必须明确知道你传的是 YAML、JSON 还是 TOML。传错路径或没指定后缀，ReadConfig 会静默失败或 panic，而不是报“不支持的格式”。
cleanenv.ReadConfig 只认文件后缀，不解析内容
cleanenv 依赖文件扩展名决定解析器：
-
.yaml/.yml→ YAML 解析器 -
.json→ JSON 解析器 -
.toml→ TOML 解析器 -
.env→ 不支持（它不是配置文件，而是环境变量源；要用ReadEnv单独加载）
常见错误现象：
- 把
config（无后缀）或app.conf当作 YAML 加载 →ReadConfig返回unsupported config format - 文件内容是 YAML，但命名为
config.json→ 解析器按 JSON 处理，报语法错误
正确做法：
立即学习“go语言免费学习笔记（深入）”；
- 始终用标准后缀：
config.yaml、secrets.json - 不要依赖构建工具重命名文件（如某些 CI 会 strip 后缀）
- 如果必须用无后缀文件，先读取内容，再手动调用
yaml.Unmarshal或json.Unmarshal，绕过ReadConfig
cleanenv.ReadEnv 和 ReadConfig 的优先级不是“自动合并”
cleanenv 没有内置的“先读 YAML 再用 ENV 覆盖”函数。你得自己控制顺序：
-
ReadConfig("config.yaml", &cfg)仅从文件填充结构体 -
ReadEnv(&cfg)仅从环境变量填充结构体 - 环境变量覆盖逻辑只在同一个调用中生效（比如
PORT=8081 cleanenv.ReadConfig("config.yaml", &cfg)会覆盖port字段），但前提是字段上声明了env:"PORT"
容易踩的坑：
Alibabacloud Sdk Client Initialization For Golang
下载
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 先调
ReadEnv，再调ReadConfig→ 文件值会把环境变量冲掉（因为后者是写入操作） - 两个都调但没设
env:tag → 环境变量完全不生效 - 在结构体里混用
yaml:和env:，但漏写其中一个 → 对应来源的值永远进不来
推荐做法：
- 只用
ReadConfig，并在所有字段上同时声明yaml:和env: - 必填项加
env-required:"true"，避免环境变量缺失时静默用零值 - 默认值统一用
env-default（比在结构体字段初始化更可靠，因为后者会被ReadConfig覆盖）
嵌套结构体字段必须显式加 yaml: tag 才能被 ReadConfig 识别
cleanenv 不递归扫描嵌套结构体的字段；它只看顶层字段的 tag。如果嵌套结构体本身没带 yaml:，它的字段即使有 tag 也不会被解析。
例如：
type Config struct {
Server struct {
Port int `yaml:"port"`
} `yaml:"server"` // ← 这个 tag 必须存在！
}漏掉 <code>yaml:"server"：
-
Server.Port永远是 0，YAML 中的server.port: 3000完全被忽略
其他注意事项：
- 嵌套结构体字段名必须首字母大写（导出）
-
yaml:tag 的 key 要和 YAML 缩进后的键名完全一致（区分大小写，不接受下划线转驼峰） - 不支持
inline或omitempty等高级 yaml.v3 特性；cleanenv底层用的是简化版解析逻辑
cleanenv 的多格式支持是“格式切换”，不是“格式融合”。你要么读 YAML，要么读 JSON，不能让一个 ReadConfig 调用同时处理两者。真正的复杂场景（比如 base.yaml + prod.json 合并），得自己用 os.ReadFile + yaml.Unmarshal + json.Unmarshal 手动拼装——cleanenv 不做这件事。
