Go bufio.Writer 忘记 Flush 为什么文件内容不完整

用 bufio.NewWriter 写文件时，Write 成功只说明数据进入了缓冲写入器，不代表数据已经到达 os.File。如果函数返回前没有调用 Flush，留在缓冲区里的尾部内容就不会被写入文件；数据量较大时，还可能出现前半段存在、最后几行缺失的文件。

修复要点是：写入结束后先检查 writer.Flush()，再根据可靠性要求调用 file.Sync()，最后关闭文件；不要把 defer file.Close() 当成 bufio.Writer 的自动 Flush。

先看清 Write、Flush、Sync 和 Close 的边界

bufio.Writer 是包在 io.Writer 外面的缓冲层。官方文档对 Flush 的定义很直接：把当前缓冲数据写入底层 io.Writer。因此，小批量数据如果没有填满缓冲区，文件可能几乎没有内容；大批量数据则可能只有已经自动刷出的部分。

把 Flush 放进可返回错误的关闭流程

最容易留下半截文件的写法是只延迟关闭文件。file 并不知道外面还有一个 bufio.Writer，所以应该显式 Flush，并把它放在文件 Close 之前。导出函数也不应只返回循环中的错误，否则最后一次 Flush 失败会被掩盖。

func writeReport(path string, rows []string) (err error) {
    // 先打开底层文件，后续所有错误都要回传给调用方。
    file, err := os.Create(path)
    if err != nil {
        return err
    }
    writer := bufio.NewWriterSize(file, 32*1024)

    // 关闭文件只负责释放文件资源，不能替代 writer.Flush。
    defer func() {
        if closeErr := file.Close(); err == nil && closeErr != nil {
            err = closeErr
        }
    }()

    for _, row := range rows {
        // 每行写入缓冲区；写入错误立即停止，避免继续生成坏文件。
        if _, err = writer.WriteString(row + "\n"); err != nil {
            return err
        }
    }

    // Flush 可能在这里首次暴露磁盘、管道或网络写入错误。
    if err = writer.Flush(); err != nil {
        return err
    }
    return nil
}

这个顺序的关键不是“多调用一个方法”，而是让错误边界与资源边界对齐。若 Flush 失败，函数必须返回失败；若已经 Flush 成功但 Close 失败，也不应把 Close 错误静默吞掉。对于不可重试的导出任务，调用方还可以把临时文件改名为正式文件，避免把半成品暴露给下游。

什么时候还需要 Sync

Flush 解决的是缓冲层到文件写入器的传递，os.File.Sync 的语义则是请求把文件当前内容提交到稳定存储。普通缓存、临时导出或可重建报表通常只需正确 Flush；账单、审计快照或不能轻易重建的文件，才需要根据系统的持久性要求评估 Sync 的成本。

// Flush 成功后再决定是否要求更强的持久化语义。
if err := writer.Flush(); err != nil {
    return err
}
if durable {
    // Sync 的开销和语义由底层文件系统决定，不要无条件添加。
    if err := file.Sync(); err != nil {
        return err
    }
}

如果程序写的是管道、HTTP 响应或压缩器，底层对象未必是普通文件，Sync 也可能不存在或没有同样含义。先确认底层 io.Writer 的类型，再决定是否需要更强的提交动作。

用最终内容校验发现半截文件

只检查 WriteString 的返回值仍然不够，因为尾部 Flush 可能失败。批量导出可以为文件约定一个尾部标记，例如最后一行写入 EXPORT_END，关闭后重新读取并确认标记存在。对固定格式文件，也可以比较预期字节数或记录数。

func hasExportFooter(path string) (bool, error) {
    // 重新读取最终文件，校验的是落盘结果而不是内存中的 rows。
    data, err := os.ReadFile(path)
    if err != nil {
        return false, err
    }
    // 尾部标记用于区分完整导出和中途截断的文件。
    return bytes.HasSuffix(data, []byte("EXPORT_END\n")), nil
}

线上排查时可先看三个信号：文件大小是否总在固定阈值附近、缺失内容是否集中在尾部、日志里是否记录了 Flush 错误。若多个写入任务共享底层 Writer，还要确认是否存在并发写入或提前 Close；这类问题不是单独补一行 Flush 就能解决的。

常见问题

为什么小文件比大文件更容易出现空文件？

小文件通常没有填满 bufio.Writer 的缓冲区，所有内容都停留在内存里，函数返回后只关闭底层文件就会丢失。

Flush 成功后还要不要 Close？

要。Flush 负责发送缓冲内容，Close 负责释放文件资源；两者职责不同，关闭错误也应该被记录。

只调用 file.Sync 能代替 Flush 吗？

不能。Sync 作用于文件本身，未 Flush 的数据可能还没到达文件对象，先 Flush 再按需 Sync 才是清晰的顺序。