为什么直接 os.WriteFile 不算原子写入
因为磁盘写入不是瞬间完成的，os.WriteFile 会先清空原文件再写入新内容。如果中途崩溃或被中断，文件就处于损坏或截断状态——用户读到的是半截数据，而不是旧版或新版。
真正的原子写入必须保证：要么是完整的旧内容，要么是完整的新内容，中间态不可见。
- Linux/macOS 下靠
rename(2)系统调用实现：先写入临时文件（同目录），再用os.Rename替换原文件——该操作在绝大多数文件系统上是原子的 - Windows 下略有不同：
os.Rename在跨卷时会失败，且对已打开的文件句柄行为不一致；需用syscall.MoveFileEx配合MOVEFILE_REPLACE_EXISTING - 临时文件名必须带随机后缀（如
fmt.Sprintf("%s.%d.tmp", base, rand.Int())），否则并发写入可能冲突
用 os.Rename 实现跨平台原子写入的关键步骤
核心逻辑是「写临时 → 同步落盘 → 原子重命名」，缺一不可。漏掉 Sync() 可能导致 rename 后读到缓存中的脏数据；没检查错误则掩盖了权限/磁盘满等真实问题。
- 临时文件必须和目标文件在同一个文件系统（即同目录），否则
os.Rename会退化为拷贝+删除，失去原子性 - 写完临时文件后，必须调用
f.Sync()（或os.File.Sync()），不能只靠Close()—— 因为某些 OS 的 close 不保证元数据落盘 - 重命名前建议先
os.Remove目标文件（可选但推荐）：避免 Windows 上因文件被占用导致 rename 失败 - 示例关键片段：
tmp := path + ".tmp" f, _ := os.Create(tmp) f.Write(data) f.Sync() // 必须 f.Close() os.Rename(tmp, path) // Linux/macOS 安全；Windows 需捕获 error 并 fallback
Windows 下 os.Rename 失败时的 fallback 方案
Windows 对正在被读取的文件加共享锁，此时 os.Rename 会返回 ERROR_ACCESS_DENIED。这不是 bug，而是设计使然——你得主动处理它。
立即学习“go语言免费学习笔记（深入）”；
- 检测错误是否为
syscall.ERROR_ACCESS_DENIED（需导入syscall） - fallback 逻辑：用
syscall.MoveFileEx，传入MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH - 注意：Go 标准库的
os.Rename在 Windows 下内部就用了MoveFileEx，但它默认不设MOVEFILE_REPLACE_EXISTING，所以失败后手动调一次更可靠 - 不要尝试「删旧→写新」：如果删旧成功、写新失败，文件就彻底丢失了
并发写入同一文件时容易忽略的竞态点
多个 goroutine 同时调用原子写入函数，若共用一个临时文件名（比如硬编码 .tmp），就会相互覆盖——最终 rename 的可能是 A 写的临时文件，但内容却是 B 覆盖过的。
- 临时路径必须唯一：推荐用
filepath.Join(os.TempDir(), "myapp-", strconv.FormatInt(time.Now().UnixNano(), 36))或os.CreateTemp（Go 1.16+） -
os.CreateTemp更安全：自动处理命名冲突、权限、清理，且返回的*os.File已打开，可直接写 - 即使用了唯一临时名，也要注意：如果两个写入几乎同时完成 rename，后一个会覆盖前一个——这是预期行为，但业务层需确认是否允许「最后写入获胜」
- 需要强一致性（如配置热更新不允许丢变更）？那就得加外部锁（
sync.RWMutex）或用文件锁（syscall.Flock）
临时文件没清理、重命名后没删残留、跨文件系统误用 rename——这些细节不出错则已，一出就是线上静默数据损坏。别省那几行代码。
