Go读JSON配置文件的核心卡点是结构体字段必须导出（首字母大写）、json标签必须精确对齐（如json:"user_name"）、字节流须由os.ReadFile()获取并传给json.Unmarshal()，任一缺失均导致字段静默为零值。
Go 读 JSON 配置文件不是“读个文件”那么简单，核心卡点在：结构体字段必须导出 + json: 标签必须对齐 + 字节流不能传错。跳过任一环节，值就静默为零（""、0、false），不报错但逻辑错。
json.Unmarshal 必须传 []byte，不能传文件路径或 *os.File
常见错误是写 json.Unmarshal("config.json", &cfg) 或 json.Unmarshal(file, &cfg)，结果 panic 报 invalid character 'c' looking for beginning of value——其实是把字符串 "config.json" 当成 JSON 内容了。
- 正确做法：先用
os.ReadFile("config.json")拿到[]byte，再喂给json.Unmarshal - 如果文件可能带 UTF-8 BOM（比如 Windows 编辑器保存的），得提前切掉：
bytes.TrimPrefix(data, []byte("\xef\xbb\xbf")) - 相对路径以
os.Executable()所在目录为基准，不是go run当前目录；调试时建议用绝对路径或打印os.Getwd()确认
结构体字段必须首字母大写，且几乎都要加 json:"xxx" 标签
Go 的 encoding/json 依赖反射，只处理导出字段（首字母大写）。没标签时默认按 Go 驼峰规则映射（DBHost → dbHost），但配置键通常是 db_host 或 database-url，不加标签就解析失败，且完全静默。
-
UserName string对应{"user_name": "alice"}？不行，必须写UserName string `json:"user_name"` - 连字符、大小写不一致的键（如
"max-retries"、"AuthEnabled"）必须显式写进 tag，否则字段为零值 - 嵌套对象也一样：外层字段要导出+加 tag，内层 struct 字段也要导出+加各自 tag
- 数组字段写成
Items []Item `json:"items"`，别漏掉[]和 tag
遇到未知字段、空值、类型不匹配时怎么不崩
配置文件会迭代，老代码跑新 JSON 很容易遇到多出字段、字段为空、数字写成字符串等问题。默认行为要么 panic，要么静默丢数据。
立即学习“go语言免费学习笔记（深入）”；
-
json: unknown field "timeout_ms"？说明 struct 少定义了字段；不想改结构体，可加一个Extra json.RawMessage字段兜底，后续按需解析 - 数字字段实际是字符串（如
"port": "8080"），int接收会报cannot unmarshal string into Go struct field；稳妥做法是先用float64或string接，再手动转 - 字段可选且需区分“未提供”和“值为 0”，用指针：
Timeout *int `json:"timeout"`，之后检查if cfg.Timeout != nil - 想让解析器严格拒绝未知字段（防 typo），用
json.NewDecoder并调dec.DisallowUnknownFields()（Go 1.19+）
大配置文件或只取个别字段时，别硬 Unmarshal
几百 KB 以上的 JSON（比如带大量注释或嵌套的 config.json），用 json.Unmarshal 加载全量字节再解析，既浪费内存又难定位错误行号。真要读深层字段（如 "database.pool.max_connections"），gjson 更直接。
- 安装：
go get github.com/tidwall/gjson - 示例：
v := gjson.GetBytes(data, "database.pool.max_connections")，然后用v.Exists()和v.IsNumber()判断再取值 - 注意：路径大小写敏感；数组索引越界（如
"items.5.name"但只有 3 项）会返回Exists()==false；v.String()遇到null返回空字符串，掩盖缺失，务必先v.Type == gjson.String - 如果项目同时支持 YAML 和 JSON，注意
go-yaml对空字符串""和null的处理与encoding/json不同，可能导致同一份配置行为不一致
最易被忽略的是：字段名首字母小写、漏写 json: 标签、把路径字符串当 JSON 内容传——这三类问题都不会报错，但字段永远是零值，排查时容易绕远路查 JSON 格式或文件权限。
