json.Marshal 返回 error 通常意味着值包含无法序列化的类型，如函数、channel、map 键非基本类型或 MarshalJSON 方法 panic。
json.Marshal 返回 error 时通常意味着什么
Go 的 json.Marshal 失败，基本只有一类原因：**值包含无法序列化的类型**。它不会因为字段名大小写、空结构体或 nil 指针本身报错（nil 指针会被编码为 null），但一旦遇到不支持的类型（比如函数、channel、map 键不是基本类型、未导出字段被强制访问等），就会返回非 nil 的 error。
常见错误现象包括：
json: unsupported type: func()json: unsupported type: map[interface {}]string-
json: error calling MarshalJSON for type xxx: ...（自定义类型的MarshalJSON方法 panic 或返回 error）
如何安全调用 json.Marshal 并定位问题源头
不要忽略 err，也不要只打印 err.Error() 就完事。关键是要知道「哪个字段」导致失败。推荐做法是分层检查：
- 对结构体字段逐个
json.Marshal测试（尤其关注map、interface{}、嵌套结构体） - 确认所有 map 的键类型是可比较的 Go 基本类型（
string、int、bool等），map[any]string或map[struct{}]int都会失败 - 若用了自定义类型，检查其是否实现了
MarshalJSON() ([]byte, error)，且该方法内部不 panic、不返回无效 JSON - 避免在结构体中直接嵌入不可序列化字段（如
http.ResponseWriter、*sql.DB），应使用-tag 或重命名字段
常见易踩坑场景与修复示例
下面这段代码看似正常，实则会在运行时报错：
立即学习“go语言免费学习笔记（深入）”；
type User struct {
Name string
Data map[interface{}]string // ❌ 键是 interface{}，不支持
}
u := User{Name: "Alice", Data: map[interface{}]string{"age": "30"}}
b, err := json.Marshal(u) // err != nil
修复方式很简单，统一键类型：
type User struct {
Name string
Data map[string]string // ✅ 改成 string 键
}
另一个典型陷阱是嵌套了未导出字段的结构体：
type Inner struct {
id int // 小写，未导出 → json.Marshal 会跳过，但如果用 json.RawMessage 或反射强读，可能出错
}
type Outer struct {
Inner
}
这种组合本身不会让 json.Marshal 报错，但若你手动调用 json.Marshal(Outer.Inner)，就会因 id 不可访问而触发反射异常 —— 实际上这时 panic 会先于 error 返回，所以务必用 defer/recover 包裹可疑调用。
生产环境建议的封装模式
别每次手动写 if err != nil { ... }。可以封装一个带上下文的日志化序列化函数：
func MustMarshal(v interface{}, ctx string) []byte {
b, err := json.Marshal(v)
if err != nil {
log.Printf("json.Marshal failed in %s: %v, value: %+v", ctx, err, v)
panic(err) // 或返回零值、上报 metrics，按团队规范来
}
return b
}
注意：ctx 字符串要具体，比如 "api.LoginResponse"，而不是笼统的 "response"。线上排查时，日志里看到失败上下文，能立刻锁定模块和数据形态。
复杂结构体 + 动态字段的场景下，json.Marshal 的错误信息往往不够直观；真正难的不是“怎么捕获 error”，而是“怎么快速反推哪个字段坏了”。多用 fmt.Printf("%#v", v) 看原始值，比猜更可靠。
