Go bufio.Writer 写入成功但 Flush 报错如何处理

Go 里调用 bufio.Writer.Write 返回成功，只能说明字节已经被缓冲写入器接收；真正把缓冲内容交给底层文件、连接或自定义 io.Writer 的动作发生在 Flush。因此，Write 成功而 Flush 报错并不矛盾，正确做法是把 Flush 当作这次输出的最终结果来判断。

官方地址：https://pkg.go.dev/bufio

写入成功和 Flush 报错分别代表什么

bufio.Writer 在 io.Writer 外面增加了一层缓冲。小块数据通常先写入内存，缓冲区满了才自动向底层 Writer 写入；最后剩余的数据需要显式 Flush。所以 n == len(data) 的含义是“本次数据已被 bufio 接收”，不是“文件已经落盘”或“网络对端已经收到”。

官方文档还说明，底层写入一旦出错，Writer 会记录这个错误，后续写入和 Flush 都会返回错误。因此不要只检查循环中的 WriteString，而把最后的 Flush 当成无关紧要的收尾动作。

把 Flush 返回值放进主流程

最小可靠写法是：先检查业务写入，再显式调用 Flush，最后关闭文件。关闭动作本身也可能报错，但它不能替代 Flush，因为 bufio.Writer 不是文件对象。

package main

import (
    "bufio"
    "fmt"
    "os"
)

func writeReport(path string, lines []string) (err error) {
    // Create 打开目标文件；返回错误时不要继续创建缓冲 Writer。
    file, err := os.Create(path)
    if err != nil {
        return fmt.Errorf("create report: %w", err)
    }
    defer func() {
        // 只有前面没有错误时，才把 Close 的错误作为最终错误返回。
        if closeErr := file.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("close report: %w", closeErr)
        }
    }()

    writer := bufio.NewWriter(file)
    for _, line := range lines {
        // WriteString 只确认数据进入 bufio 缓冲层。
        if _, err = writer.WriteString(line + "\n"); err != nil {
            return fmt.Errorf("buffer report: %w", err)
        }
    }
    // Flush 才是把剩余缓冲交给文件 Writer 的关键结果。
    if err = writer.Flush(); err != nil {
        return fmt.Errorf("flush report: %w", err)
    }
    return nil
}

这里使用命名返回值，是为了让延迟执行的 Close 在前面没有错误时补充关闭错误；它并没有掩盖 Flush 的失败。若 Flush 已经失败，函数会保留更早、更能解释问题的错误。

按底层 Writer 判断怎么处理

Flush 报错的根因不在 bufio 这一层，而在它包装的目标 Writer。文件可能遇到磁盘满、权限变化或文件系统错误；网络连接可能在 Flush 时断开；自定义 Writer 还可能返回短写。处理时先记录目标、已处理的业务标识和原始错误，再决定是否重试。

func export(writer *bufio.Writer, payload string) error {
    // 先写入缓冲层；短写也必须视为失败。
    n, err := writer.WriteString(payload)
    if err != nil {
        return fmt.Errorf("write payload: %w", err)
    }
    if n != len(payload) {
        return fmt.Errorf("short buffered write: got %d, want %d", n, len(payload))
    }
    // 不忽略 Flush，因为错误可能只在这里暴露。
    if err := writer.Flush(); err != nil {
        return fmt.Errorf("flush payload: %w", err)
    }
    return nil
}

对于文件导出，Flush 失败时不要直接把文件标记为“已生成”。对于消息、HTTP 响应或追加日志，重试前要确认底层协议是否可能已经收到部分数据；如果无法判断，就给这次写入分配幂等标识，避免简单重试造成重复内容。

Flush、Close 和 Sync 的边界要分清

Flush 负责把 bufio 中尚未发送的数据写给底层 Writer；Close 负责关闭文件句柄；Sync 是文件对象向操作系统请求同步的额外动作。需要更强持久化语义时，顺序通常是 Flush -> Sync -> Close，但这依然不代表远端副本或业务流程已经成功。

如果 Flush 失败，先保留原始错误，不要通过 Reset 清掉错误后继续复用同一个 Writer。只有在你已经明确丢弃当前缓冲、切换到新的目标，并且业务允许重新生成内容时，才考虑重新建立写入链路。

常见问题

为什么 Write 返回 nil，Flush 却返回错误？

因为 Write 可能只写入 bufio 的内存缓冲，Flush 才首次调用底层 Writer。底层磁盘、连接或自定义 Writer 的问题会在这个时点暴露。

只调用 file.Close 能不能自动解决？

不能把它当作可靠方案。应先显式检查 Flush，再处理 Sync 和 Close；否则缓冲数据可能根本没有交给文件对象。

Flush 失败后能不能马上重试？

先判断目标是否可能已经部分接收，再依据业务幂等性选择重试、回滚或人工补偿。对网络输出尤其不能无条件重复发送。

什么时候还需要调用 Sync？

当业务要求文件在操作系统故障后仍尽可能保留时，再考虑 Flush 后调用 Sync；普通临时输出通常只需正确处理 Flush 和 Close 的错误。