Sonic在Linux ARM64平台不提供预编译native库，仅支持darwin/arm64和linux/amd64；需手动构建native core或降级至v1.8.3纯Go版本，且必须启用CGO并使用含gcc/clang的完整基础镜像。
sonic 在 ARM64 上只支持 macOS，Linux ARM64 需手动编译
直接 go get github.com/bytedance/sonic 后在 linux arm64（如树莓派、aws graviton）上运行会失败：找不到预编译的 native 二进制，cgo_enabled=1 下仍报 undefined reference to sonic_*。这不是配置问题，是官方分发策略限制——目前仅提供 linux/amd64 和 darwin/arm64 的预编译产物。
可行路径只有两条：
- 降级使用
sonic v1.8.3（最后一个带源码 fallback 的版本），它不依赖预编译 native 库，纯 Go + CGO 兼容层可编译，但会丢失time.Time直接格式化等新特性 - 自行从源码构建 native core：
cd $GOPATH/pkg/mod/github.com/bytedance/sonic@v1.9.5/native，运行make build-linux-arm64（需系统已安装clang、cmake和 ARM64 交叉工具链），再确保CGO_CFLAGS="-I$(pwd)/include"等环境变量生效
别试 -tags "arm64" —— sonic 不识别该 tag，且不会触发任何 ARM 优化分支。
CGO 必须启用，且不能用 Alpine 或精简 Go 发行版
即使你在 macOS ARM64 上开发，只要目标部署环境是 Linux ARM64，就绕不开 CGO。而很多 CI/CD 流程默认用 golang:alpine 镜像，它不含 gcc、clang，也缺少 libc 符号，会导致编译时卡在 github.com/bytedance/sonic/loader 找不到。
关键检查点：
- 运行
go env CGO_ENABLED，必须为1；若为0，所有 sonic 性能优势归零，退化为纯 Go 模拟路径（比标准库还慢） - 构建命令中显式带上
CGO_ENABLED=1，不要依赖环境默认值 - 基础镜像改用
golang:1.21.10-slim或ubuntu:24.04，并安装build-essential和clang
go build -gcflags="-m" | grep "sonic.*encoder" 若无输出，大概率是 CGO 失效导致 JIT 编译未触发。
避免 map[string]interface{}，优先定义 struct 并显式限制 RecursiveDepth
ARM64 CPU 缓存小、分支预测弱，泛型路径（map[string]interface{}）下 sonic 无法生成专用汇编，全程走解释器模式，性能反超标准库 20%+。你看到的 benchmark 数字，全是基于结构体实测出来的。
正确做法：
- 对固定 schema 输入（如 API 请求体），定义
type OrderReq struct { ID int `json:"id"` }，而非var m map[string]interface{} - 初始化 sonic 时显式设深度：
sonic.Config{CompileOptions: option.CompileOptions{RecursiveDepth: 3}}—— 90% 的业务结构体 ≤3 层，限制后 JIT 编译量下降 70%，首请求延迟从 20ms 降到 3ms - 若必须用
map（如网关透传），至少在init()中预热一次：sonic.Marshal(map[string]interface{}{"a": 1})，让泛型编译器落地一个缓存项
别信 “sonic 支持 interface{} 就等于动态 JSON 友好” —— 它支持，但不快；快的前提是类型可静态推导。
time.Time 和错误处理必须重写适配逻辑
ARM64 上 time.Now().UnixNano() 计算开销略高于 x86，而 sonic 默认把 time.Time 当整数序列化，看似省事，实则和业务约定（RFC3339）冲突。更麻烦的是，sonic.Unmarshal 对 nil 指针 panic 在 ARM 上恢复更慢（C++ 异常跨架构转换开销更大）。
必须做的三件事：
- 启动时注册时间格式：
sonic.RegisterTimeFormat("2006-01-02T15:04:05Z07:00")，否则Unmarshal会静默截断或解析失败 - 解码前检查指针是否为 nil：
if u == nil { u = new(User) }，别依赖NoNullSliceOrMap: true兜底 —— 它在 ARM 上对 slice 初始化有额外内存屏障开销 - 错误判断必须用
errors.As(err, &sonic.InvalidCharacterError{})，不能只写err != nil；ARM 上errors.Is的反射路径更重，易被编译器去优化
最易忽略的一点：ARM64 上 sonic.UnmarshalString 相比 Unmarshal 的性能收益比 x86 更明显（约 18%），因为字符串到字节切片的转换在 ARM 上成本更高。如果原始数据已是 string（比如 HTTP header 或 Redis GET 返回），优先选前者。
