Go csv.Writer.UseCRLF 导出 Windows CSV 有什么影响

Go 的 encoding/csv.Writer 默认使用 LF（\n）结束每条记录。把 UseCRLF 设为 true 后，记录行结束符改成 CRLF（\r\n）。它解决的是换行兼容性，不会改变逗号分隔、字段引号，也不会自动把 UTF-8 转成某种 Windows 字符集。

官方地址：https://pkg.go.dev/encoding/csv#Writer.UseCRLF

因此，导出文件需要交给旧版桌面工具、Windows 侧脚本或约定使用 CRLF 的下游系统时，可以显式启用它；如果文件主要进入 Linux 服务、Git 仓库或已经能正确读取 LF 的解析器，则保持默认值通常更简单。

先分清 LF 与 CRLF 的差别

CSV 的一条记录由字段组成，记录之间还需要一个行结束符。csv.Writer 的默认行为是使用 LF；UseCRLF=true 只把这个结束符替换成 CRLF。两种输出的字段值、逗号位置和必要的引号转义仍由同一个 Writer 负责。

需要特别注意的是，CRLF 并不等于“Windows 编码”。换行符是文本内容的一部分，而字符编码决定中文等字符怎样表示；如果下游系统要求特定编码，仍要单独设计编码转换链路，不能只改 UseCRLF。

最小写法：第一次 Write 前启用 UseCRLF

配置要放在第一次 Write 或 WriteAll 之前。下面的示例把 CSV 写到内存，便于把 Writer 的职责限制在“生成字段和换行”这一层。

package main

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

func exportWindowsCSV() ([]byte, error) {
	var buf bytes.Buffer
	w := csv.NewWriter(&buf)
	// 只把每条记录的结束符改为 CRLF，不改变字段分隔和编码。
	w.UseCRLF = true

	rows := [][]string{
		{"姓名", "部门"},
		{"林晓", "研发"},
	}
	for _, row := range rows {
		// Write 可能先把记录放进 Writer 的内部缓冲区。
		if err := w.Write(row); err != nil {
			return nil, fmt.Errorf("写入 CSV 记录失败: %w", err)
		}
	}
	// Flush 把缓冲内容推送给 bytes.Buffer。
	w.Flush()
	if err := w.Error(); err != nil {
		return nil, fmt.Errorf("刷新 CSV 失败: %w", err)
	}
	return buf.Bytes(), nil
}

func main() {
	data, err := exportWindowsCSV()
	if err != nil {
		fmt.Println(err)
		return
	}
	// 示例只展示生成结果的字节长度，不把输出误当作编码转换证明。
	fmt.Println("CSV bytes:", len(data))
}

这段代码的关键是配置顺序：一旦开始写入，就不要再把换行策略当作运行时开关反复修改。导出接口可以在创建 Writer 时接收一个布尔配置，但应在写第一条记录之前完成设置。

规模化导出时，换行策略要放在边界上

当导出服务同时面对多个下游，问题不在于“Windows 一定只能读 CRLF”，而在于接口是否明确声明了文本格式。现代 CSV 读取器通常能处理常见换行，但老工具、脚本拼接逻辑或人工打开文件的流程可能对行结束符更敏感。

可以把导出链路拆成三个边界：

1. 数据边界：业务层决定每个字段的值和列顺序。
2. 序列化边界：csv.Writer 决定逗号、引号和 LF/CRLF；UseCRLF 只作用于最后一项。
3. 传输边界：文件存储、HTTP 下载或消息传递负责把已生成的字节交给下游，不应偷偷替换换行。

这样做的好处是，出现“打开后行数不对”时可以先确认下游是否把 CRLF 当成两个换行，再判断是否真的存在字段引用或编码问题。不要因为换行差异就修改逗号、强行拆分带引号的多行字段。

Write、Flush 和 Error 要成对出现

Writer.Write 是带缓冲的写入。单条 Write 成功并不等于底层文件或网络流已经收到全部数据；完成循环后要调用 Flush，再通过 Error 读取写入或刷新过程中记录的错误。

func writeCSV(w io.Writer, rows [][]string) error {
	csvWriter := csv.NewWriter(w)
	// 只有协议明确要求 Windows 风格换行时才打开该选项。
	csvWriter.UseCRLF = true

	for _, row := range rows {
		// Writer 会负责必要的字段引用，不要手工拼接逗号和换行。
		if err := csvWriter.Write(row); err != nil {
			return fmt.Errorf("写入记录失败: %w", err)
		}
	}
	// 把最后一批缓冲字节发送到底层 Writer。
	csvWriter.Flush()
	if err := csvWriter.Error(); err != nil {
		return fmt.Errorf("输出 CSV 失败: %w", err)
	}
	return nil
}

如果不需要逐条处理错误，也可以使用 WriteAll；官方实现会在写完记录后调用 Flush，并返回刷新错误：

func writeAllCSV(w io.Writer, rows [][]string) error {
	csvWriter := csv.NewWriter(w)
	// 选项仍须在 WriteAll 之前设置，WriteAll 会使用当前 Writer 配置。
	csvWriter.UseCRLF = true
	if err := csvWriter.WriteAll(rows); err != nil {
		return fmt.Errorf("批量输出 CSV 失败: %w", err)
	}
	return nil
}

哪些场景应该开，哪些场景保持默认

换行开关最好是导出接口的显式策略，而不是根据运行操作系统隐式决定。服务部署在 Linux，并不代表交付文件就一定只给 Linux 使用；同样，部署在 Windows 也不意味着所有 CSV 都需要 CRLF。

发布前的格式清单

1. 确认下游协议需要 LF 还是 CRLF，并把选择写进导出接口或配置说明。
2. 确认 UseCRLF 在第一次 Write 或 WriteAll 前设置。
3. 逐条写入时，在循环结束后调用 Flush 并检查 Error。
4. 使用 WriteAll 时检查其返回值，不要因为它内部刷新就忽略错误。
5. 把换行、字段分隔、引号转义、字符编码分别验收，避免用一个开关解决四类问题。

一句话总结：UseCRLF=true 只是把每条 CSV 记录的行结束符从 LF 改成 CRLF；是否启用取决于消费协议，而不是 Go 程序运行在哪个操作系统。

相关问题

UseCRLF 会改变 CSV 的逗号分隔符吗？

不会。逗号仍由 Writer.Comma 控制，UseCRLF 只改变记录行结束符。

打开 UseCRLF 后中文会变成 Windows 编码吗？

不会。它不做字符集转换；如果消费方要求特定编码，需要在 CSV 序列化之后单独处理字节编码。

只调用 Write 不调用 Flush 可以吗？

不建议。Write 使用缓冲，完成写入后应调用 Flush 并检查 Error；使用 WriteAll 时要检查它返回的刷新错误。