Go os.File.Sync 真的能保证数据落盘吗：写入、同步与错误处理边界

日志服务偶发重启后，最后几条记录没有出现在文件里，第一反应往往是“是不是忘了调用 Sync”。这个判断只对了一半：os.File.Sync 能把当前文件内容提交到稳定存储，但它不是事务提交，也不会替你保证目录项和多个文件一起落盘。

需要把一份文件当作“已经写好并可恢复”的结果时，至少分别检查 Write、Sync 和 Close 的错误；如果采用临时文件替换，还要把目录同步纳入恢复设计。

先从 Write、Sync、Close 的错误分层开始

下面的示例把每个返回值都留下来。示例故意不把 Close 写成只在 defer 中调用，因为关闭阶段也可能暴露缓存刷新或文件描述符错误。

package main

import (
    "errors"
    "fmt"
    "os"
)

func writeStable(path string, data []byte) error {
    f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
    if err != nil {
        return fmt.Errorf("open: %w", err)
    }

    n, err := f.Write(data)
    if err != nil {
        _ = f.Close()
        return fmt.Errorf("write %d bytes: %w", n, err)
    }
    if n != len(data) {
        _ = f.Close()
        return errors.New("short write")
    }
    if err := f.Sync(); err != nil {
        _ = f.Close()
        return fmt.Errorf("sync: %w", err)
    }
    if err := f.Close(); err != nil {
        return fmt.Errorf("close: %w", err)
    }
    return nil
}

这里的控制流很朴素，却能回答三个常见误区：Write 的 n 要核对，Sync 失败时不能继续宣称成功，Close 失败也要向上返回。不要把“函数返回 nil”理解成硬盘、文件名和业务状态已经同时提交。

为什么 Sync 不能替代原子替换

直接覆盖目标文件时，进程在写入中途退出，目标文件可能只剩部分内容。更稳妥的做法是先写同目录临时文件，完成同步和关闭后再用 os.Rename 替换目标。这样读者要么看到旧文件，要么看到完整的新文件，而不是依赖覆盖过程的中间状态。

func replaceFile(target string, data []byte) error {
    tmp, err := os.CreateTemp(filepath.Dir(target), ".settings-*")
    if err != nil {
        return err
    }
    tempName := tmp.Name()
    keep := false
    defer func() {
        if !keep {
            _ = os.Remove(tempName)
        }
    }()

    if _, err := tmp.Write(data); err != nil {
        _ = tmp.Close()
        return err
    }
    if err := tmp.Sync(); err != nil {
        _ = tmp.Close()
        return err
    }
    if err := tmp.Close(); err != nil {
        return err
    }
    if err := os.Rename(tempName, target); err != nil {
        return err
    }
    keep = true
    return nil
}

这段代码用于说明顺序，生产实现还要补上 path/filepath 导入、权限继承和平台差异处理。关键点是 Sync 作用在临时文件内容上；Rename 改变的是目录项。若恢复目标包含断电后的目录一致性，就要在重命名成功后打开父目录并调用目录的同步能力，同时接受不同操作系统对目录同步的差异。

线上排查时按这条顺序复查

先确认写入是否完整

记录 n、err 和目标路径，先排除短写、磁盘空间不足、权限变化。只看业务日志里的“保存成功”没有用，必须确认写入函数确实检查了返回值。

再确认同步是否成功

把 Sync 的错误单独打点，不要和网络重试混成一个“保存失败”。同步失败时可以保留临时文件供现场分析，但不能把它标成可恢复快照。

最后确认关闭与替换

检查 Close 是否被忽略、Rename 是否发生在同一文件系统，以及异常退出后目录里是否留下可识别的临时文件。排查顺序要和代码顺序一致，否则很容易只盯着 Sync。

几个容易写错的边界

• 把 Sync 当事务：它只处理当前文件内容，不会提交数据库记录、目录项和其他文件。
• 只返回 Write 错误：后续 Sync、Close 仍有独立失败可能。
• 临时文件放在别的目录：跨文件系统时 Rename 可能失败，临时文件应与目标保持同目录。
• 只测正常退出：还要在同步失败、重命名失败和进程被终止的场景核对恢复结果。

相关问题

Write 返回 nil 就代表数据已经落盘吗？

不是。它说明这次写调用没有报告错误，是否提交到稳定存储要看后续同步策略。

Close 之后还能再调用 Sync 吗？

不应这样设计。同步应在关闭前完成，关闭后的文件对象已不适合继续承担写入流程。

为什么临时文件要和目标文件放在同一目录？

同目录通常能保持同一文件系统，使 Rename 具备原子替换的前提，也方便最后处理目录项持久化。

把成功定义写进代码

文件持久化不是加一行 Sync 就结束。更可靠的成功定义应该写成可观察的阶段：写入长度正确、文件内容同步成功、文件关闭成功、替换成功，以及业务需要时父目录同步成功。每一阶段都留下错误和恢复动作，重启后再用校验或版本号验证最终文件，这比单独追问“有没有调用 Sync”更接近真实故障的边界。