当前位置：首页 > 文章列表 > Golang > Go教程 > Go bufio.Writer Flush 失败时的资源收尾

Go bufio.Writer Flush 失败时的资源收尾

来源：17golang原创 2026-09-29 00:19:13 0浏览收藏

bufio.Writer.Flush() 返回错误时，正确做法不是立刻结束收尾，而是保存 Flush 错误，并继续关闭底层资源。Flush 负责把内存缓冲区交给底层 io.Writer，Close 负责释放文件描述符或连接；这是两个不同职责，任何一个失败都不能替代另一个。

我第一次认真处理这个问题，是在一个批量导出任务里：主体循环没有报错，文件也能看到，但结尾偶尔缺数据。原因并不神秘——最后一批数据还留在 bufio.Writer 中，真正的磁盘写入错误直到 Flush 才出现，而原代码既忽略了 Flush 返回值，也没有把 Close 错误带回调用方。

官方文档：https://pkg.go.dev/bufio

Flush 失败后，Close 仍然要执行

bufio.Writer 只包装一个 io.Writer。小块数据通常先进入内存缓冲区，所以 WriteString 返回 nil，并不能证明数据已经落到文件、网络连接或其他底层目标。只有缓冲区被写满，或者代码主动调用 Flush，底层写入错误才可能暴露。

Go bufio.Writer 缓冲写入域与底层资源域的静态责任边界 — 图1：静态说明图展示缓冲写入域和底层资源域的责任边界；Flush 错误与 Close 错误属于不同的结果，关闭动作不能被省略。

这里最重要的判断有三条：

Flush 只把当前缓冲数据写给底层 Writer，它不会替你关闭底层文件。
即使 Flush 失败，底层文件描述符仍然需要 Close；否则长时间运行的进程可能积累资源。
Close 本身也可能返回错误。对持久化结果敏感的任务，不应把它当成永远成功的清理动作。

三个常见写法为什么不够稳

1. 直接 defer Flush，却不接收错误

func writeBad(path string, data []byte) error {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    defer f.Close() // 错误被忽略，调用方不知道关闭是否成功

    w := bufio.NewWriter(f)
    defer w.Flush() // Flush 的返回值同样被丢弃

    _, err = w.Write(data)
    return err
}

这个版本看起来简洁，但最关键的两个收尾错误都没有进入返回值。尤其是函数主体写入成功、最后 Flush 失败时，调用方会收到 nil，误以为文件已经完整写好。

2. 先 Close 文件，再 Flush 缓冲区

顺序反过来后，Flush 会尝试向已经关闭的文件写入，失败几乎是必然的。正常收尾应先 Flush，再 Close；但不论 Flush 成功与否，都要尝试 Close。

3. Flush 一报错就 return

if err := w.Flush(); err != nil {
    return fmt.Errorf("flush: %w", err) // 这里返回会跳过后续显式 Close
}
if err := f.Close(); err != nil {
    return fmt.Errorf("close: %w", err)
}

如果没有独立的 defer 兜底，这段代码在 Flush 失败时不会执行 Close。问题不在“是否应该返回 Flush 错误”，而在返回前没有完成资源释放。

我更常用的写法：显式 Flush，defer 兜底 Close

对普通文件输出，我倾向于让正常路径清楚可见：业务写入成功后显式 Flush；文件关闭由 defer 保证一定执行，同时把 Close 错误与当前返回错误合并。这样早退路径和 Flush 失败路径都不会漏掉文件关闭。

package report

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

func WriteLines(path string, lines []string) (retErr error) {
    f, err := os.Create(path)
    if err != nil {
        return fmt.Errorf("create output: %w", err)
    }

    // 无论业务写入或 Flush 在哪里失败，都关闭底层文件并保留 Close 错误
    defer func() {
        if closeErr := f.Close(); closeErr != nil {
            retErr = errors.Join(retErr, fmt.Errorf("close output: %w", closeErr))
        }
    }()

    w := bufio.NewWriterSize(f, 64*1024)
    for _, line := range lines {
        if _, err := w.WriteString(line + "\n"); err != nil {
            // Write 已返回错误时，Writer 会锁存错误，不再做无意义的 Flush 重试
            return fmt.Errorf("write buffered data: %w", err)
        }
    }

    // Flush 成功只表示缓冲数据已交给底层 Writer，不代表 Close 一定成功
    if err := w.Flush(); err != nil {
        return fmt.Errorf("flush buffered data: %w", err)
    }

    return nil
}

errors.Join 会忽略 nil，并保留所有非空错误，适用于 Go 1.20 及以上版本。因此当 Flush 失败、随后 Close 也失败时，调用方能同时看到两个原因；当 Flush 成功但 Close 失败时，函数依然返回 Close 错误。

这段写法没有显式在正常路径调用 Close，是因为 defer 已经承担了关闭职责。若业务要求“Close 成功后才能执行重命名、提交状态”等后续动作，可以把 Close 改成显式调用，并用布尔变量避免 defer 再次关闭。

把写入、Flush 和 Close 错误都带回调用方

Go 缓冲写入、Flush、Close 错误与 errors.Join 的静态映射关系 — 图2：静态结构图把三个错误来源映射到统一返回值，errors.Join 会忽略 nil，同时保留非空错误的因果链。

实际项目中可以按下面的优先级理解错误：

错误来源	通常说明	仍需执行的动作
Write / WriteString	缓冲区写满时触发底层写入，或输入处理失败	关闭底层资源；不要继续向同一个 Writer 写
Flush	尚未下沉的数据无法完整交给底层 Writer	保留错误并 Close；不要把 Close 当作补救写入
Close	释放或最终关闭底层资源失败	返回或记录错误；不要盲目重复 Close

如果项目仍使用 Go 1.19 或更早版本，可以保留第一个业务错误，并把 Close 错误包装进日志或自定义错误类型。不要为了兼容旧版本而直接丢弃 Close 错误。

为什么 Flush 失败后不该原地重试

官方文档明确说明：一旦 bufio.Writer 在写入底层 Writer 时遇到错误，它将不再接受新数据；后续写入和 Flush 都会返回该错误。也就是说，Writer 会“锁存”第一次底层写错误。

这也是我不建议写 for i := 0; i 的原因。重复调用并不会自动恢复磁盘空间、网络连接或底层 Writer 状态，也不会重新获得已经发生不确定性的写入位置。

如果业务确实需要重试，应把重试设计放在更高一层：

保留原始业务数据，而不是依赖 bufio 内部尚未写出的字节。
关闭失败的底层资源，重新创建文件或连接。
从明确的偏移、临时文件或幂等请求边界重新写入。
只有在确定数据不会重复或截断时，才把重试结果提交为最终产物。

Writer.Reset(newWriter) 会丢弃未 Flush 的缓冲数据并清除错误状态。它适合复用缓冲对象，不是“无损恢复失败写入”的按钮。没有保留原始数据时调用 Reset，可能把尚未下沉的内容直接丢掉。

用可控失败 Writer 理解错误出现的位置

下面的小型 Writer 只允许写入有限字节，可用于理解“业务 Write 看似成功，错误却在 Flush 才暴露”的现象。它是教学示例，不代表磁盘或网络的全部失败模式。

package main

import (
    "bufio"
    "errors"
    "fmt"
    "io"
)

type limitedWriter struct {
    remaining int
}

func (w *limitedWriter) Write(p []byte) (int, error) {
    // 底层目标容量耗尽后，直接返回一个可识别错误
    if w.remaining == 0 {
        return 0, errors.New("simulated destination full")
    }

    n := len(p)
    if n > w.remaining {
        n = w.remaining
    }
    w.remaining -= n

    if n

这个例子要表达的不是某个固定输出，而是错误边界：缓冲写入成功只代表数据进入了内存；Flush 的返回值才说明剩余数据是否被底层 Writer 接受。