Go encoding/csv 怎样跳过注释行并保留空字段

Go 读取带说明行的 CSV 时，不需要先用 strings 手工过滤，再按逗号切割。encoding/csv 的 csv.Reader 可以通过 Comment 忽略符合规则的注释行；连续分隔符产生的空字段不会被吞掉，而是作为 "" 保留在记录中。生产代码再配合 FieldsPerRecord、TrimLeadingSpace 和明确的错误分支即可。

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

先区分注释行和空字段

这两个问题经常同时出现在配置导入、批量用户数据和运营表格中，但它们的处理位置不同。注释行是“整行是否进入解析流程”的判断；空字段是“记录进入解析后，某一列是否有值”的结果。前者由 Reader.Comment 控制，后者由 CSV 的分隔符结构保留。

例如输入中有 # generated by job，它应该被当作说明行跳过；输入 alice,,admin 时，第二列仍然存在，只是值为空。若先把空字符串过滤掉，第三列会被错误地当成第二列，后续入库或字段映射都会错位。

Comment 和空字段是两套规则

创建 Reader 后，在第一次调用 Read 或 ReadAll 前设置 Comment。官方规则要求注释字符是有效 rune，且不能与分隔符相同；行首没有前置空白时才会触发忽略。带前置空白的行不会因为设置了 TrimLeadingSpace 就自动变成注释行。

package main

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

func main() {
    input := "# generated by job\n" +
        "alice,,admin\n" +
        " # this line has leading whitespace\n"

    reader := csv.NewReader(strings.NewReader(input))
    // 只有行首直接出现 # 时才按注释行忽略。
    reader.Comment = '#'
    // 让每一列都保留在 record 中，空列会成为空字符串。
    reader.FieldsPerRecord = -1

    for {
        record, err := reader.Read()
        if err == io.EOF {
            // EOF 是正常结束，不应当作为导入失败。
            break
        }
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("字段数=%d, 记录=%q\n", len(record), record)
    }
}

这段示例把 FieldsPerRecord 设为 -1，表示允许不同记录拥有不同字段数，便于先观察输入结构。输出中的 alice,,admin 仍然是三个字段；带前置空白的 # 行则会进入解析，若业务不允许这种格式，应在导入前明确拒绝或单独清洗。

用 Read 保留空字段并正确结束循环

Read 返回一条记录和一个错误。没有更多数据时返回 io.EOF；解析失败时可能同时返回部分记录和解析错误。不要用 err != nil 直接把所有情况当成失败，也不要只检查 len(record) 来判断是否读完。

func readCSV(input string) ([][]string, error) {
    reader := csv.NewReader(strings.NewReader(input))
    // # 只作为行首注释标记，避免把字段中的 # 当成注释。
    reader.Comment = '#'
    // -1 表示记录字段数可变；固定格式时见下一节的正数配置。
    reader.FieldsPerRecord = -1

    var records [][]string
    for {
        record, err := reader.Read()
        if err == io.EOF {
            // 正常读完输入，返回已经收集的记录。
            return records, nil
        }
        if err != nil {
            // 解析错误不能静默跳过，否则列错位会进入后续业务。
            return nil, fmt.Errorf("read csv: %w", err)
        }
        // 不过滤空字符串，保证字段下标与 CSV 列位置一致。
        records = append(records, record)
    }
}

如果要长期保存记录，直接追加返回的切片即可。若把 reader.ReuseRecord 设为 true 来减少分配，则必须在保存前复制记录，因为后续读取可能复用同一底层数组；不需要优化前不要打开这个开关。

固定列数时设置 FieldsPerRecord

导入接口通常有固定列契约，例如每条数据必须包含用户名、邮箱和角色三列。这时设置正数的 FieldsPerRecord，字段数不匹配会返回 csv.ErrFieldCount 相关错误。零值会以第一条记录的字段数作为后续要求；负数才是不检查字段数。

func newUserReader(input string) *csv.Reader {
    reader := csv.NewReader(strings.NewReader(input))
    // 只有没有前置空白的 # 行会被忽略。
    reader.Comment = '#'
    // 用户名、邮箱、角色三列必须始终存在；某列没有值仍是空字符串。
    reader.FieldsPerRecord = 3
    // 只有业务明确允许去掉字段左侧空白时才打开它。
    reader.TrimLeadingSpace = false
    return reader
}

固定列数不等于每一列都必须非空。alice,,admin 可以通过三列检查，但应用层仍应决定邮箱是否必填。解析器负责分隔、引号和字段数；必填项、默认值和业务校验应放在解析成功之后。

空白、引号和注释字符的边界

CSV 中的空白默认属于字段内容。TrimLeadingSpace 为 true 时，字段左侧空白会被忽略，但这不是“把整行左移后再判断 Comment”。因此如果上游把 # note 当作注释，最好在文件契约层统一要求注释字符必须位于行首，不要依赖模糊的预处理。

字段值中出现 # 也不会自动变成注释，例如 alice,#tag,admin 的第二列是 #tag。如果字段包含逗号、换行或引号，应让 encoding/csv 处理标准 CSV 引号规则，不要直接使用 strings.Split(line, ",")。

生产读取循环：分别处理记录、EOF 和错误

把读取逻辑放在一个小函数中，有利于统一错误信息和字段契约。下面的写法保留解析错误的原始信息，调用方可以继续用 errors.As 提取 *csv.ParseError 的行号、列号和底层错误。

func loadUsers(input string) error {
    reader := csv.NewReader(strings.NewReader(input))
    // 注释标记与 Comma 不冲突，并且必须在第一次 Read 前配置。
    reader.Comment = '#'
    // 这类导入固定三列，空值仍占据对应列位置。
    reader.FieldsPerRecord = 3

    for {
        record, err := reader.Read()
        if err == io.EOF {
            // 所有记录已处理完毕，进入提交或收尾阶段。
            return nil
        }
        if err != nil {
            // 保留底层 ParseError，便于上层记录行列位置。
            return fmt.Errorf("load users: %w", err)
        }
        if record[0] == "" {
            // 这是业务校验，不要把空字段从 record 中删除。
            return fmt.Errorf("username is empty")
        }
        // 在这里执行字段映射或写入；record[1] 仍对应邮箱列。
    }
}

上线前的最小检查清单

• 注释格式：确认上游的注释字符位于行首，并决定带前置空白的标记行是数据还是非法输入。
• 列位置：用连续分隔符覆盖空字段样例，确认业务代码按下标读取，而不是先过滤空字符串。
• 字段契约：固定列数就设置正数 FieldsPerRecord；列数确实可变才使用 -1。
• 错误边界：只把 io.EOF 当作正常结束，其他错误保留上下文并交给调用方处理。
• 资源边界：从文件读取时用 defer file.Close()，并让解析器只负责 CSV 语法，业务必填项另行校验。

常见问题

为什么设置 Comment 后，带空格的 # 行没有被跳过？

因为 Comment 要求注释字符位于行首，前面不能有空白。若这类行本来就是注释，应在上游统一格式；若不能控制上游，就在进入 csv.Reader 前做有明确规则的预处理，并记录其代价。

空字段会不会让后面的列向前移动？

不会。连续分隔符会产生一个值为空的字段，后面的列仍保持原下标。只有业务代码主动过滤空字符串，才会造成列错位。

FieldsPerRecord 应该设为 0 还是 -1？

固定格式可以设为正数；零值会用第一条记录的字段数约束后续记录；明确允许字段数变化时使用 -1。不要为了“先跑起来”长期关闭字段数检查。

能不能用 ReadAll 简化代码？

小文件可以使用 ReadAll，它会读取剩余记录并在成功时返回 nil 错误；大文件或需要逐条校验、限流和及时失败时，逐条调用 Read 更容易控制内存与错误边界。