encoding/csv 跳过注释行与空行的读取配置

用 Go 的 encoding/csv 读取配置文件或数据导入文件时，最容易误判的是“空行”和“空白行”其实不是一回事。标准库会自动忽略完全空行；以 Comment 字符开头的行可以通过 Reader.Comment 忽略；但只含空格或制表符的行仍可能进入字段解析。

先分清三类行：空行、空白行和注释行

可以把 CSV Reader 看成一个有边界的文本过滤器：它先判断换行分隔出的内容属于哪一类，再决定是否生成一条记录。完全空行没有字段内容，默认会被忽略；注释行需要通过 Comment 明确指定；而一行如果含有空格，即使视觉上“看起来是空的”，也不能直接当成空行。

注释字符也有一个很重要的位置规则：它必须出现在行首。假设 Comment 设置为 #，那么 # generated file 可以被忽略，而 # generated file 的前导空格会让这一行不再是标准的注释行。不要先凭肉眼判断输入文件，应该把字符位置纳入排查。

用 Comment 跳过真正的注释行

Comment 的类型是 rune。它保持默认值 0 时不启用注释过滤；设置为 #、; 等合法字符后，Reader 才会忽略从行首直接以该字符开头的行。注释字符不能与逗号相同，也不能是换行符或 Unicode 替换字符。

package main

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

func readCSVText(input string) error {
	reader := csv.NewReader(strings.NewReader(input))
	reader.Comment = '#' // 只忽略行首直接以 # 开头的注释行。
	reader.TrimLeadingSpace = true // 去掉字段前导空白，不改变注释识别规则。
	reader.FieldsPerRecord = -1 // 允许不同记录拥有不同数量的字段。

	for {
		record, err := reader.Read()
		if err != nil {
			if err == io.EOF { // EOF 代表正常读完，不是解析失败。
				return nil
			}
			return fmt.Errorf("读取 CSV 失败: %w", err) // 保留原始解析错误便于定位输入行。
		}
		fmt.Printf("%q\n", record) // 这里只展示记录，不代表真实业务输出。
	}
}

上面的示例把“允许字段数变化”作为单独决策。若业务要求每条记录必须有相同列数，不要为了绕过错误直接设置为 -1；应该保留默认的字段数检查，并把不符合约定的输入当成可追踪的导入错误。

用 FieldsPerRecord 决定字段数策略

FieldsPerRecord 有三种常用语义：

默认值为 0 时，第一条有效记录会建立字段数基准。这里的“第一条有效记录”不是文件的第一行文字：注释行和完全空行会先被排除。因此，如果文件开头有注释和空行，真正的表头或第一条数据记录才会影响后续的字段数判断。

TrimLeadingSpace 只能处理字段前导空白

TrimLeadingSpace 经常被误解成“忽略空白行”。它做的是字段级处理：当字段开头存在空格或制表符时，可以去掉这段前导空白。它不会把只含空格的一整行变成标准空行，也不会让行首带空格的 # 自动变成注释。

func newReader(input string) *csv.Reader {
	reader := csv.NewReader(strings.NewReader(input))
	reader.Comment = ';' // 配置文件使用分号作为行首注释字符。
	reader.TrimLeadingSpace = false // 保留字段前导空格时明确写出选择。
	reader.FieldsPerRecord = 0 // 让第一条有效记录建立字段数基准。
	return reader
}

如果输入格式规定“缩进后的注释也应忽略”，需要在进入 csv.Reader 之前增加一个有明确规则的预处理层，并说明它如何处理引号、字段中的换行和空格。不要只打开 TrimLeadingSpace 就假设它完成了行级预处理，因为那会把字段语义和注释语义混在一起。

把文件关闭、EOF 和字段错误放在同一条读取路径

实际导入代码通常还要负责打开文件、关闭资源和区分正常结束与格式错误。下面的函数只做一件事：把读到的记录交给回调。它保留标准库的错误位置，让调用方决定是终止批次、记录坏行，还是进入人工修复流程。

package csvimport

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

func ReadFile(path string, handle func([]string) error) error {
	file, err := os.Open(path)
	if err != nil {
		return fmt.Errorf("打开 CSV 文件失败: %w", err) // 打开失败时不进入 Reader。
	}
	defer file.Close() // 无论读取成功或失败，都释放文件描述符。

	reader := csv.NewReader(file)
	reader.Comment = '#' // 忽略行首的配置说明注释。
	reader.FieldsPerRecord = 3 // 业务模板固定为三列，字段数错误应尽早暴露。

	for {
		record, err := reader.Read()
		if err == io.EOF { // EOF 只代表正常读完，不是失败。
			return nil
		}
		if err != nil {
			return fmt.Errorf("解析 CSV 失败: %w", err) // ErrFieldCount 等错误保留在链路中。
		}
		if err := handle(record); err != nil {
			return fmt.Errorf("处理 CSV 记录失败: %w", err) // 业务处理错误不伪装成解析错误。
		}
	}
}

读取条数不对时，按这张清单排查

1. 先打印或抽取原始行，确认所谓的“空行”是否实际包含空格、制表符或不可见字符。
2. 确认 Comment 字符是否真的位于行首；前导空格不会因为设置了 TrimLeadingSpace 就改变注释规则。
3. 检查注释字符是否与字段分隔符相同，或是否使用了换行符等非法字符。
4. 确认 FieldsPerRecord 是业务想要的固定值、默认推断还是可变字段模式。
5. 如果仍然出现字段错误，再检查引号、换行和分隔符，而不要先把所有字段数检查关闭。

结论：把过滤规则和字段规则分开配置

这类问题的稳定解法不是寻找一个“跳过所有空内容”的总开关，而是把三个决策拆开：Comment 负责行首注释，标准 Reader 负责完全空行，TrimLeadingSpace 负责字段前导空白，FieldsPerRecord 负责记录结构。输入文件越不规整，越应该保留这些边界，让错误能落到具体规则上。

常见问题

为什么设置了 Comment，带空格的注释行还被读出来？

因为标准注释判断要求 Comment 字符出现在行首。前导空格会让它变成普通字段内容；TrimLeadingSpace 也不会改变这一行级判断。

空白行会被 csv.Reader 自动忽略吗？

完全空行会被忽略，但只含空格或制表符的行不等同于完全空行，可能被解析为字段。是否清理它，应由输入协议或前置处理规则明确决定。

什么时候应该设置 FieldsPerRecord 为 -1？

只有当可变列确实是业务格式的一部分，或者业务层有自己的列数处理逻辑时才使用。固定模板导入通常应保留字段数检查，让错误尽早暴露。