Go CSV 导出写入失败后怎么通过 Writer.Error 找到原因

Go 的 encoding/csv.Writer 写 CSV 时，单次 Write 返回 nil，并不等于底层文件、网络响应或压缩流已经成功接收全部数据。正确做法是：逐条写入时立即检查 Write 返回值；所有记录完成后调用 Flush；最后再调用 Writer.Error() 读取写入或刷新阶段记录的错误。若使用 WriteAll，它会自动执行 Flush，但仍建议检查返回值。

记住一句话：Write 负责把记录交给 CSV 写入器，Flush 负责把缓冲区交给底层 writer，Error 负责确认这条链路有没有在收尾时失败。

先看清 Go CSV Writer 的缓冲边界

csv.NewWriter 接收的是一个 io.Writer，例如文件、内存缓冲区、HTTP 响应或压缩 writer。CSV 记录不会每次都立即写到底层目标，单条记录会先经过必要的转义和缓冲。因此，下面这种写法只能证明记录已经交给了 csv.Writer：

w := csv.NewWriter(dst)
if err := w.Write([]string{"1001", "paid"}); err != nil {
    return err // 记录格式化或之前记录的写入错误在这里返回
}
// 此时不要把 Write 成功当成底层文件已经完成写入

官方文档明确要求在所有数据写完后调用 Flush，并通过 Error 检查错误。Flush 本身没有返回值，所以不能写成 if err := w.Flush(); ...；错误要从 w.Error() 读取。

推荐的检查顺序：Write、Flush、Error

导出函数最好把错误传播集中在一个出口，既能及时发现中途失败，也能捕获最后一批缓冲数据写出时的失败：

package export

import (
    "encoding/csv"
    "fmt"
    "io"
)

func WriteCSV(dst io.Writer, rows [][]string) error {
    w := csv.NewWriter(dst)
    for index, row := range rows {
        if err := w.Write(row); err != nil {
            // 记录序号只用于定位问题，保留底层错误作为原因
            return fmt.Errorf("写入第 %d 条 CSV 记录失败: %w", index+1, err)
        }
    }

    w.Flush() // 把最后一批缓冲数据交给底层 io.Writer
    if err := w.Error(); err != nil {
        // Flush 没有返回值，收尾错误必须从 Writer.Error 读取
        return fmt.Errorf("刷新 CSV 输出失败: %w", err)
    }
    return nil
}

这段代码的关键不是把 Error 当作普通的“最后一次 Write 返回值”，而是把它作为整个 writer 生命周期的收尾检查。对文件导出、HTTP 流式响应和 gzip 等包装 writer，调用方都可以沿用这个顺序。

用失败的 io.Writer 看懂 Error 何时出现

为了理解错误传播，可以构造一个在写入超过指定次数后失败的 writer。这个例子不是生产环境的文件权限检查，而是用于说明：底层错误可能发生在 Flush 真正写出缓冲区时。

type failWriter struct {
    writes int
    limit  int
}

func (f *failWriter) Write(p []byte) (int, error) {
    f.writes++
    if f.writes > f.limit {
        // 模拟磁盘、网络或下游 writer 在写出阶段拒绝数据
        return 0, errors.New("模拟底层写入失败")
    }
    return len(p), nil
}

func demo() error {
    dst := &failWriter{limit: 0}
    w := csv.NewWriter(dst)

    if err := w.Write([]string{"id", "status"}); err != nil {
        return err // 小记录可能仍停留在 csv.Writer 的缓冲区
    }
    w.Flush()
    if err := w.Error(); err != nil {
        // 这里才能观察到 Flush 转交底层 writer 时记录的错误
        return fmt.Errorf("CSV 输出失败: %w", err)
    }
    return nil
}

在这个示意中，Write 的结果和最终输出结果是两个时刻。真实项目不应依赖“刚好写了多少次”来判断失败，而应把 Flush 和 Error 固定写进正常路径。若底层 writer 本身有更具体的错误类型，可以用 errors.Is 或 errors.As 在上层做分类处理。

WriteAll 适合简单导出，逐条 Write 适合精确定位

如果数据已经整理成 [][]string，且只需要知道整个批次成功还是失败，可以使用 WriteAll：

w := csv.NewWriter(dst)
if err := w.WriteAll(rows); err != nil {
    // WriteAll 内部会调用 Write 和 Flush，并返回 Flush 的错误
    return fmt.Errorf("批量导出 CSV 失败: %w", err)
}

如果需要在大批量导出中定位第几条数据、遇到错误后停止继续生成，或者记录每条数据的业务标识，则应使用逐条 Write。不管选择哪种方式，都不要忽略返回值，也不要在 Flush 后省略 Error 检查。

上线前的 CSV 错误检查清单

• 每次逐条 Write 都检查返回的 error。
• 逐条写入模式在函数结尾调用一次 Flush。
• Flush 后调用 Writer.Error()，不要期待 Flush 返回错误。
• 需要批量语义时可用 WriteAll，并检查它的返回值。
• 用 %w 包装错误，让上层仍能使用 errors.Is 或 errors.As。

常见问题

为什么 Write 返回 nil，文件却可能不完整？

因为 CSV Writer 会缓冲记录，底层写入可能延迟到 Flush。只有完成刷新并检查 Error，才完成了这条写出链路的错误确认。

Flush 之后还需要检查 Error 吗？

需要。Flush 没有错误返回值，官方 API 用 Writer.Error 报告之前 Write 或 Flush 发生的错误。

WriteAll 还要手动调用 Flush 吗？

通常不需要，WriteAll 会在内部调用 Flush 并返回刷新错误；直接检查 WriteAll 的返回值即可。

相关官方文档：https://pkg.go.dev/encoding/csv#Writer.Error