Go 导出 UTF-16 CSV 时怎么正确连接 csv.Writer 和编码转换器

Go 的 encoding/csv 只负责把字段组织成 CSV，并不会自动把输出变成 UTF-16。正确的连接方式是：先让 csv.Writer 把字符串写成 CSV，再把它包在 transform.Writer 上游，让编码转换器把收到的 UTF-8 字节转换为指定端序的 UTF-16。

可以把写入链记成一句话：记录 → csv.Writer → transform.Writer → 文件。CSV 层处理逗号、引号、换行和 UseCRLF；UTF-16 层处理字节序和 BOM。两层职责不要颠倒。

导出 UTF-16 CSV 时，csv.NewWriter 的底层 writer 应该是编码转换器；写完先刷新 CSV 缓冲，再关闭转换器，最后分别处理两层错误。

先把写入链排成一条线

csv.Writer 接收的是 io.Writer，而 transform.NewWriter 返回的对象同样可以作为 io.Writer。因此组合关系应该是：

记录 [][]string
  ↓
csv.Writer：字段转义、分隔符、换行
  ↓
transform.Writer：UTF-8 字节 → UTF-16 字节
  ↓
os.File / bytes.Buffer / 其他 io.Writer

如果把顺序反过来，先创建 UTF-16 字节再交给 csv.Writer，CSV writer 就无法把这些字节当作正常的 Go 字符串字段处理，转义和换行边界也会变得混乱。导出层应保留“先组织文本格式、后转换编码”的方向。

UTF-16 的端序和 BOM 先选清楚

golang.org/x/text/encoding/unicode 提供 UTF16 构造函数，可以明确指定默认端序和 BOM 策略。对于要交给常见桌面表格工具打开的导出文件，示例选择小端序并写入 BOM：

enc := unicode.UTF16(
    unicode.LittleEndian, // 选择 UTF-16LE，避免把端序交给平台猜测
    unicode.UseBOM,       // 在输出开头写入 BOM，帮助消费方识别字节序
)

UseBOM 表示输出可以带 BOM；如果协议已经明确规定了端序，也可以使用 IgnoreBOM，让文件不额外插入标记。这里的关键不是“哪种策略永远最好”，而是让导出约定与接收方的文件格式约定一致。

用一条 writer 链生成 UTF-16 CSV

下面的函数把一批记录写入任意 io.Writer。它没有把结果先拼成一个大字符串，适合后续改成文件、内存缓冲或 HTTP 响应输出。

package main

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

    "golang.org/x/text/encoding/unicode"
    "golang.org/x/text/transform"
)

// writeUTF16CSV 先组织 CSV，再把 UTF-8 文本转换为 UTF-16LE 字节。
func writeUTF16CSV(dst io.Writer, records [][]string) error {
    encoder := unicode.UTF16(
        unicode.LittleEndian, // 固定输出端序，避免平台差异
        unicode.UseBOM,       // 输出 BOM，便于文件接收方识别编码
    ).NewEncoder()
    encodedWriter := transform.NewWriter(dst, encoder)
    csvWriter := csv.NewWriter(encodedWriter)
    csvWriter.UseCRLF = true // 桌面表格场景常用 CRLF 作为行结束符

    // WriteAll 会写入每条记录并刷新 csv.Writer 自己的缓冲区。
    if err := csvWriter.WriteAll(records); err != nil {
        // 转换器仍可能持有尾部状态，失败路径也尝试关闭它。
        _ = encodedWriter.Close()
        return fmt.Errorf("write csv: %w", err)
    }

    // 关闭转换器会把最后尚未输出的编码状态写入 dst。
    if err := encodedWriter.Close(); err != nil {
        return fmt.Errorf("close utf-16 encoder: %w", err)
    }
    return nil
}

这里的关键是 csv.NewWriter(encodedWriter)，而不是 csv.NewWriter(dst) 后再想办法转换已经产生的字节。WriteAll 会调用 CSV writer 的 Flush 并返回刷新错误；随后仍要关闭编码转换器，因为转换器可能需要在最后一次输入后写出收尾字节。

Flush 和 Close 的顺序决定文件尾部是否完整

如果采用逐条 Write，推荐把收尾动作写得更显式：

csvWriter := csv.NewWriter(encodedWriter)
csvWriter.UseCRLF = true

for _, record := range records {
    // 每次 Write 只负责提交一条记录，错误要立即返回。
    if err := csvWriter.Write(record); err != nil {
        _ = encodedWriter.Close()
        return fmt.Errorf("write record: %w", err)
    }
}

// csv.Writer 有自己的缓冲；不 Flush，记录可能还没交给编码器。
csvWriter.Flush()
if err := csvWriter.Error(); err != nil {
    _ = encodedWriter.Close()
    return fmt.Errorf("flush csv: %w", err)
}

// 最后关闭 transform.Writer，让转换器完成尾部编码。
if err := encodedWriter.Close(); err != nil {
    return fmt.Errorf("close encoder: %w", err)
}

可以把两个动作分开理解：

• csvWriter.Flush() 负责把 CSV writer 缓冲的数据交给它的底层 writer。
• csvWriter.Error() 负责报告此前 Write 或 Flush 记录的错误。
• encodedWriter.Close() 负责结束转换器并把最终编码字节交给真正的输出目标。

因此不要在 CSV 还没刷新时先关闭编码器，也不要只检查 csvWriter.Write 的返回值就直接认为文件已经完成。只要中间任意一层发生短写或底层 I/O 错误，都应该保留错误上下文。

批量导出时保留同一条链

大文件导出不需要把所有记录先转换成一个 []byte。可以先打开输出文件，再沿用同一条转换链逐条写入；这样 CSV 的转义仍由标准库处理，编码转换也只维护一个连续状态。

import "os"

func exportFile(path string, records [][]string) error {
    file, err := os.Create(path)
    if err != nil {
        return fmt.Errorf("create output: %w", err)
    }
    defer file.Close() // 释放文件描述符；写入错误仍由 writer 链返回

    return writeUTF16CSV(file, records)
}

如果需要更严格地处理文件关闭错误，可以把文件对象的关闭动作提到函数尾部显式处理；示例重点是 writer 的层级，而不是把整个导出任务变成一次性内存操作。

几个容易混淆的选择

常见问题

为什么导出的文件大小不像 UTF-8 CSV？

UTF-16 通常会为多数字符使用两个字节，并可能额外带 BOM，所以文件大小变化是正常现象。真正需要确认的是写入链是否把 UTF-8 文本交给了 UTF-16 encoder，而不是把 UTF-16 字节再次当作字符串交给 CSV writer。

只调用 csvWriter.Flush 不关闭编码器可以吗？

不建议。Flush 只完成 CSV writer 这一层的刷新，转换器仍可能有尚未写出的尾部状态。完成 CSV Flush 和错误检查后，应继续关闭 transform.Writer。

WriteAll 后还需要再调用 csvWriter.Flush 吗？

通常不需要，WriteAll 已经会刷新 CSV writer 并返回刷新错误。但无论使用逐条 Write 还是 WriteAll，都要完成编码转换器的 Close。

什么时候不应使用 UseBOM？

当接收协议明确规定不允许 BOM，或上下游已经通过外部协议固定了端序时，应按协议选择 IgnoreBOM。BOM 是文件格式约定的一部分，不是修复乱码的万能开关。

小结

这类导出的稳定写法只有三个要点：让 csv.Writer 位于编码转换器上游；用 unicode.UTF16 明确端序和 BOM 策略；结束时先处理 CSV 缓冲，再关闭转换器并检查错误。把这条链封装成接收 io.Writer 的函数后，文件、内存缓冲和其他输出目标都可以复用同一套逻辑。