Go 32 位平台原子操作未对齐怎么办

Go 代码在 amd64 上运行正常，切到 386、32 位 ARM 或 32 位 MIPS 后，64 位原子读写却出现异常，通常要先查字段布局，而不是先怀疑业务锁。旧式 sync/atomic.LoadInt64、AddInt64 等函数把 64 位对齐责任交给调用方；如果 int64 或 uint64 藏在结构体中间，32 位架构的字段排列就可能让它落在不满足要求的偏移上。

官方接口地址：https://pkg.go.dev/sync/atomic

最稳妥的修复是把需要原子访问的字段改成 atomic.Int64 或 atomic.Uint64，让类型本身负责 32 位平台的对齐；如果因为兼容旧代码必须继续传递 *int64，就要把它当成布局契约管理，不能用一个看似整齐的填充字段掩盖风险。

先分清是哪一种原子类型

sync/atomic 同时保留了两类 API。第一类是接收地址的旧式函数，例如 atomic.LoadInt64(&x)；在 32 位 ARM、386 和 32 位 MIPS 上，官方文档明确要求调用方安排 64 位字的对齐。第二类是 Go 1.19 加入的 typed atomic 类型，例如 atomic.Int64 和 atomic.Uint64。它们会自动对齐，方法也更容易和字段的生命周期绑定。

这个区别解释了一个常见误判：把普通 int64 字段放进结构体，再用 atomic.AddInt64 访问，并不会因为“变量类型是 64 位”就自动获得跨架构安全性。相反，atomic.Int64 是一个带内部实现约束的原子值，不能在第一次使用后复制。

为什么结构体中间的 int64 更容易出问题

在 32 位目标上，普通指针和许多基础字段的自然对齐通常是 4 字节。下面这个结构体把一个 uint32 放在 int64 前面，total 的偏移就不能仅凭字段声明顺序判断为 8 的倍数。真正的风险来自 atomic.AddInt64(&s.total, 1) 这一行：旧式原子函数需要调用方兑现它的地址契约。

package counter

import "sync/atomic"

// LegacyStats 展示旧式原子函数面对的字段布局风险。
// 在 32 位目标上，不要假定 total 因为类型是 int64 就自动满足 8 字节对齐。
type LegacyStats struct {
	flags uint32
	total int64
}

// Add 使用旧 API，调用方必须先确认 total 的地址满足平台要求。
func (s *LegacyStats) Add(n int64) {
	atomic.AddInt64(&s.total, n)
}

这里不需要把问题描述成“每个 32 位构建都会失败”。更准确的说法是：该布局不能满足旧式 API 在这些架构上的通用契约。某次分配、某种结构体排列或某个编译器版本碰巧没有暴露问题，也不能把碰巧当成保证。

用偏移量把布局问题变成可读的检查

排查时应把目标架构放进问题定义。unsafe.Offsetof 可以告诉你字段相对于结构体起点的偏移，unsafe.Alignof 可以告诉你类型自身的对齐要求；二者都只是布局信息，不会替你修复已经存在的地址。

package main

import (
	"fmt"
	"unsafe"
)

type LegacyStats struct {
	flags uint32
	total int64
}

func main() {
	// 用偏移量观察字段布局；余数不为 0 时，旧式 64 位原子访问值得阻断构建。
	offset := unsafe.Offsetof(LegacyStats{}.total)
	align := unsafe.Alignof(LegacyStats{}.total)
	fmt.Printf("total offset=%d align=%d aligned=%t\\n", offset, align, offset%8 == 0)
}

这段检查应该在目标架构下编译或运行，例如把 GOARCH=386、GOARCH=arm 纳入兼容矩阵，而不是只在当前开发机上看一次输出。检查结果只回答“字段布局是什么”，并不等于完整的并发正确性证明；数据竞争、复制原子值和生命周期设计仍然要单独处理。

# 为 32 位目标准备交叉构建变量；不要把本机 amd64 结果当成全部结论。
GOOS=linux GOARCH=386 go test ./...
GOOS=linux GOARCH=arm GOARM=7 go test ./...

优先迁移到 atomic.Int64

如果业务字段只需要计数、时间戳或单个 64 位状态值，迁移到 typed atomic 通常是最清楚的方案。类型会自动处理 32 位平台的对齐，调用方也不再需要把普通字段地址暴露给旧式函数。

package counter

import "sync/atomic"

type Stats struct {
	// Int64 自带跨 32 位平台的对齐语义；零值可以直接使用。
	total atomic.Int64
}

// Add 通过指针接收者更新原子值，避免复制包含原子状态的结构体。
func (s *Stats) Add(n int64) {
	s.total.Add(n)
}

// Total 读取一个顺序一致的原子快照。
func (s *Stats) Total() int64 {
	return s.total.Load()
}

迁移时要一起检查三个边界：调用方是否仍然需要 *int64，结构体是否会被按值传递，以及是否有序列化、反射或接口代码依赖旧字段类型。atomic.Int64 首次使用后不能复制；因此推荐让包含它的结构体使用指针传递，避免把值放进会复制它的切片扩容、返回值或赋值表达式中。

必须保留旧 API 时怎么安排字段

有些底层接口、旧版封装或 ABI 适配代码暂时只能接收 *int64。这时可以遵循官方文档给出的有限保证：分配出来的结构体、数组或切片的第一个字，以及全局变量或局部变量，可作为 64 位原子访问的对齐起点。这个规则不是“结构体任意字段都自动对齐”，也不是给字段前面加一个 uint32 就完成了修复。

package legacy

import "sync/atomic"

// AlignedCounter 把旧式原子字段放在分配对象的第一个字位置。
// 只有在接口确实要求 *int64 时才采用这种兼容布局，并保持对象不被复制。
type AlignedCounter struct {
	value int64
	flags uint32
}

// Add 依赖 value 作为分配对象的首个 64 位字，而不是依赖人为填充字段。
func (c *AlignedCounter) Add(delta int64) {
	atomic.AddInt64(&c.value, delta)
}

这是一种受限的兼容策略，不如 typed atomic 直观。不要通过 unsafe.Pointer 把一个普通字段的地址向前或向后移动，也不要把未对齐的字节切片强行转换成 *int64；那只是改变了指针表示，并没有让底层对象获得合法布局。若字段必须出现在结构体中间，优先改字段类型或改接口边界。

把修复纳入兼容矩阵

这类问题最终不是靠一条本机测试命令结束，而是要让代码选择和目标架构保持一致。可以按下面的决策表收敛方案：

我会把“字段偏移检查”和“386/ARM 交叉构建”放在同一份兼容清单中：前者负责尽早暴露布局变化，后者负责确认源码、标准库和依赖都能在目标架构上编译。若已经采用 atomic.Int64，也不要因为对齐被类型接管就忽略复制规则和数据竞争。

常见追问

只把 int64 放到结构体第一个字段就永远安全吗？

它可以利用官方对分配结构体首个字的对齐保证，但仍受旧 API、对象是否被复制和地址是否来自受支持分配方式等条件约束。新代码更建议直接使用 atomic.Int64。

atomic.Int64 能和普通 int64 互换吗？

不能按普通数值字段直接替换。它通过 Load、Store、Add 等方法读写；如果外部接口必须拿到 *int64，应重新设计接口或保留隔离的兼容层。

为什么 amd64 没暴露问题？

amd64 对 64 位原子操作和自然布局的条件更宽松，不能代表 32 位目标的调用契约。跨架构项目应以目标 GOARCH 的布局和官方文档为准。

参考资料：https://pkg.go.dev/sync/atomic、https://go.dev/doc/go1.19、https://go.dev/doc/