Go 文件原子替换后怎样安排 Sync 降低断电丢数据风险

我在做配置文件热更新时，最容易把“写入成功”和“断电后还能恢复”当成一回事。实际上，临时文件的字节内容、文件名从临时名切换到正式名，是两个不同层次的持久化问题。Go 的 os.File.Sync 负责把当前文件内容提交到稳定存储；os.Rename 负责名字切换，但不同操作系统的原子性和目录项落盘语义并不完全相同。

官方文档：https://pkg.go.dev/os#File.Sync

可复用的顺序是：同一目录创建临时文件，完整写入并检查 Write，调用临时文件的 Sync，再关闭它，最后 Rename 到正式路径；如果还要把“新名字已经落盘”纳入断电模型，再按目标系统能力处理父目录的 Sync。任何一步失败，都不要把临时结果当成已发布版本。

先把风险拆成内容层和目录项层

文件替换通常想同时达到两个目标：读者要么看到旧版本，要么看到完整的新版本，不要读到半截内容；进程重启或机器断电后，正式路径也应该尽量指向一个完整版本。临时文件加重命名能解决“写入过程中不覆盖旧文件”的问题，但它本身不等于存储设备已经把数据和目录变化都保存好了。

可以把过程画成两条边界：第一条是临时文件的内容，第二条是目录中“正式文件名指向哪个文件对象”的关系。第一次 Sync 处理前者，重命名后的目录同步处理后者。图中的箭头是静态说明，不是某次机器运行的证据。

在替换前把临时文件 Sync 完整

File.Sync 的位置应该在所有写入完成之后、重命名之前。这样即使后面的名字切换出现错误，旧文件仍然没有被覆盖，临时文件也可以留给清理逻辑处理。示例把每一个可能失败的步骤都单独留出错误出口，避免用一条过长的 defer 链掩盖关键错误。

package atomicfile

import (
    "fmt"
    "os"
    "path/filepath"
)

// Replace 写入同目录临时文件，再把完整内容切换到 target。
// Sync 的错误必须让调用方感知，不能把“写入缓存成功”当成持久化成功。
func Replace(target string, data []byte, perm os.FileMode) (err error) {
    dir := filepath.Dir(target)
    base := filepath.Base(target)

    // 临时文件放在目标目录，避免 Rename 跨文件系统失败。
    tmp, err := os.CreateTemp(dir, "."+base+".*.tmp")
    if err != nil {
        return fmt.Errorf("create temp file: %w", err)
    }
    tmpName := tmp.Name()
    defer func() {
        // 失败时只清理临时文件，不碰原来的正式文件。
        if err != nil {
            _ = os.Remove(tmpName)
        }
    }()

    if err = tmp.Chmod(perm); err != nil {
        _ = tmp.Close()
        return fmt.Errorf("chmod temp file: %w", err)
    }
    if _, err = tmp.Write(data); err != nil {
        _ = tmp.Close()
        return fmt.Errorf("write temp file: %w", err)
    }
    if err = tmp.Sync(); err != nil {
        _ = tmp.Close()
        return fmt.Errorf("sync temp file: %w", err)
    }
    if err = tmp.Close(); err != nil {
        return fmt.Errorf("close temp file: %w", err)
    }

    // 同目录 Rename 在 Unix 上通常是原子切换；跨平台语义要按目标系统确认。
    if err = os.Rename(tmpName, target); err != nil {
        return fmt.Errorf("rename temp file: %w", err)
    }
    return nil
}

这里的关键不是把每行都加注释，而是把三个容易混淆的错误点分开：Write 代表数据是否交给操作系统，Sync 代表当前文件内容是否提交到稳定存储，Close 代表文件句柄是否正常关闭。示例不吞掉 Sync 与 Close 的错误，调用方才能决定这次替换是否算成功。

为什么 Rename 不能替代 Sync

os.Rename 只是改变路径关系。它可以让读者在替换瞬间看到旧文件或新文件，而不是看到应用层主动写到正式路径的一半内容，但它并不替代临时文件的内容同步。如果跳过前面的 tmp.Sync()，重命名后正式路径可能已经切换，设备却还没有把新内容稳定保存。

还有一个经常被忽略的点：临时文件和正式文件应放在同一目录。这样既减少跨文件系统重命名的失败可能，也让目录项变化集中在同一个父目录中。Go 官方文档同时提醒，非 Unix 平台的 Rename 即使在同一目录也不保证是原子操作，所以“原子替换”不是可以脱离运行环境写死的承诺。

重命名后要不要 Sync 父目录

如果运行目标是 Unix 类文件系统，并且断电模型要求“重启后目录一定能看到这次名字切换”，常见做法是在 Rename 成功后打开父目录并调用目录文件的 Sync。但这不是一个可以在所有 Go 平台上无条件复制的统一模板：Windows 等平台对目录打开、目录句柄和 Rename 的行为不同，应用应依据目标系统文档与实际故障模型设计。

// syncDirAfterRename 只展示 Unix 类系统上的目录项同步意图。
// 跨平台程序应为不同目标系统提供单独实现或明确降级说明。
func syncDirAfterRename(dir string) error {
    d, err := os.Open(dir)
    if err != nil {
        return fmt.Errorf("open parent directory: %w", err)
    }
    defer func() {
        // 目录 Sync 的主要错误由显式返回值承接；关闭仍要执行。
        _ = d.Close()
    }()
    if err := d.Sync(); err != nil {
        return fmt.Errorf("sync parent directory: %w", err)
    }
    return nil
}

不要把这段代码当成所有平台都能直接使用的保证。更稳妥的工程做法是把“文件内容持久化”和“目录项持久化”抽象成两个步骤，Unix 目标单独实现目录同步，其他目标明确记录可用保证和测试结果；这样调用方不会误以为一个跨平台函数能提供完全相同的断电语义。

我在项目里最后保留的判断清单

我会先问这次写入能不能接受“最新版本丢失但旧版本还在”，还是必须把目录切换也纳入持久化承诺。前一种场景至少要做到同目录临时文件、写入检查、临时文件 Sync、Close、Rename；后一种场景再为 Unix 类目标补目录 Sync，并把它的错误视为发布失败。

• 临时文件与目标文件在同一目录，避免跨文件系统 Rename。
• Write、Sync、Close、Rename 分别检查错误。
• 正式文件未替换前，任何失败都不能删除或覆盖旧版本。
• 不把 Close、目录清理和内容 Sync 混成一个“保存成功”布尔值。
• 跨平台部署时，不宣传超出目标系统文档能证明的原子性和断电保证。

相关问题

只调用 Close，不调用 Sync，可以吗？

可以完成一次普通文件写入，但不能把它表述成已经主动请求内容提交到稳定存储。对允许丢失最新版本的缓存类文件，取舍可能足够；对配置、索引或状态快照，应按断电风险决定是否需要 Sync。

为什么临时文件一定要和正式文件同目录？

因为 Rename 的跨目录、跨文件系统行为限制更多。同目录能减少设备边界差异，也便于在切换后处理同一个父目录的目录项持久化。

Sync 失败后能不能继续 Rename？

如果目标是降低断电后出现半新内容的风险，不应该继续。Sync 失败意味着你没有得到预期的内容持久化结果，继续替换只会把未确认的版本暴露为正式版本。

文件原子替换的核心不是多调用几个 API，而是把每个 API 的保护对象说清楚：临时文件避免覆盖旧内容，文件 Sync 处理内容落盘，Rename 处理名字切换，目录 Sync 处理目录项持久化。把这些边界写进代码和错误处理，才能让“降低断电丢数据风险”变成可解释、可维护的工程约定。