Go 文件 Close 报错为什么不能被前面的写入错误覆盖

Go 写文件时，Close 不是一个可以随手忽略的收尾动作。数据可能还停留在 bufio.Writer，底层写入错误也可能在 Flush、Sync 或 Close 阶段才暴露。如果前面的 Write 已经失败，却在 defer 中无条件把 Close 的结果赋给返回值，真正的首个故障就会被覆盖。

正确做法是按“写入、刷新、同步、关闭”的顺序收集非 nil 错误。Go 1.20 及以上用 errors.Join 合并；旧版本至少要保证已有写入错误不被 Close 错误替换。

为什么 Close 错误不能覆盖前面的写入错误

bufio.Writer.Write 只说明数据进入了缓冲写入器。缓冲区写满时，它会尝试写到底层文件；缓冲区没有写满时，底层错误可能要等到 Flush 才出现。即使 Flush 返回 nil，要求更强持久性时还会调用 File.Sync，最后才是 File.Close。

常见的危险写法是 defer func() { err = f.Close() }()。它让 Close 的结果无条件覆盖命名返回值：前面已经得到的“磁盘空间不足”或“写入失败”可能消失，而调用方只看到最后一个关闭错误。错误文本虽然可能相似，排障所需的阶段信息已经丢了。

用 errors.Join 保留完整错误链

Go 1.20 引入的 errors.Join 会忽略 nil 值，并返回一个可以继续用 errors.Is、errors.As 检查的合并错误。实际代码中，即使 Write 已失败，也应完成必要的 Flush、Sync 和 Close，让每个阶段都有机会报告问题：

package report

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

func writeReport(path string, data []byte) error {
    f, err := os.Create(path)
    if err != nil {
        return fmt.Errorf("create report: %w", err)
    }

    w := bufio.NewWriter(f)
    var errs []error

    if _, err := w.Write(data); err != nil {
        // 保留写入阶段，避免后面的 Close 错误覆盖它。
        errs = append(errs, fmt.Errorf("write report: %w", err))
    }
    if err := w.Flush(); err != nil {
        // 缓冲区真正落到底层 writer 时，错误可能在这里出现。
        errs = append(errs, fmt.Errorf("flush report: %w", err))
    }
    if err := f.Sync(); err != nil {
        // Sync 表示把文件内容交给文件系统做更强的持久化确认。
        errs = append(errs, fmt.Errorf("sync report: %w", err))
    }
    if err := f.Close(); err != nil {
        // Close 仍需执行，它可能暴露最后的收尾错误。
        errs = append(errs, fmt.Errorf("close report: %w", err))
    }

    return errors.Join(errs...)
}

这里没有因为前一步失败就提前 return，因为提前返回会跳过 Close；也没有让 Close 独占返回值。每个错误都保留了阶段前缀，调用方仍可用 errors.Is 检查底层错误。对于不需要 Sync 的普通缓存文件，可以删掉同步步骤，但要保留“先 Flush，再 Close”的顺序。

旧版本与实际项目中的选择边界

如果项目必须兼容 Go 1.20 之前的版本，不能直接调用 errors.Join。最低限度的兼容规则是：保存第一个写入类错误，再把 Close 错误作为上下文补充；当没有前置错误时，才直接返回 Close 错误。

func mergeCloseError(first, closeErr error) error {
    if first != nil {
        // 旧版本没有 errors.Join，至少不能丢掉首个故障。
        if closeErr != nil {
            return fmt.Errorf("%w; close: %v", first, closeErr)
        }
        return first
    }
    return closeErr
}

这种写法不能像 errors.Join 那样让两个错误都参与 errors.Is 遍历，所以它更适合作为兼容层，而不是新代码的首选。选择规则可以压缩成下面这张表：

检查清单与常见误区

代码审查时可以按这五项快速判断：是否记录了 Write 错误；是否调用并检查了 Flush；是否按需求调用 Sync；是否始终执行并检查 Close；调用方是否使用 errors.Is 或 errors.As，而不是只比较最终错误字符串。

还要注意，Close 返回 nil 也不能证明业务数据一定已经被远端存储系统确认；它只代表当前文件对象的关闭没有报告错误。相反，Sync 的成本较高，不要为了“看起来完整”而给所有临时文件强行增加同步。

相关问题

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

不要依赖这种隐式行为。显式调用 Flush 能把缓冲阶段的错误放在清晰的位置，也更容易在多个收尾步骤中合并错误。

Close 报错时一定要重试吗？

不一定。先根据错误类型和文件用途判断；重试前要确认句柄、路径和写入内容是否会造成重复副作用。

为什么不只返回最早的错误？

只返回首错在兼容层里可以接受，但多个阶段都失败时，合并错误能帮助日志和调用方同时看到完整上下文。

官方文档可从 bufio.Writer.Flush、os.File.Close 和 errors.Join 源码 复查对应语义。核心原则只有一句：关闭文件要做完，关闭错误要记录，但不能让它把已经发生的写入错误抹掉。