bufio.Scanner 读取二进制零字节的边界

我第一次遇到这个问题，是把一段“看起来像文本”的协议数据交给 bufio.Scanner，结果发现记录里夹着零字节 \x00。先说结论：Scanner 不会因为看到零字节就自动截断或丢弃它；默认分词函数是 ScanLines，真正的边界仍然是换行。只有当协议明确规定 NUL 是分隔符时，才需要自定义 SplitFunc。

这一区分很重要：零字节可以被 Scanner 当作普通数据读出来，但 Scanner 仍然是“按 token 读取”的工具，不是任意二进制协议解析器。超长 token、分隔规则和返回切片生命周期，才是更容易踩坑的地方。

先看零字节到底去了哪里

我先用一个很小的输入排除猜测：字母之间放入零字节，两条记录之间用换行分开。通过 %q 打印 token，可以直接看到零字节仍在字符串中。

package main

import (
    "bufio"
    "fmt"
    "strings"
)

func main() {
    // 这里用转义序列构造包含 NUL 的两行输入。
    input := "A\x00B\nC\x00D\n"
    scanner := bufio.NewScanner(strings.NewReader(input))

    for scanner.Scan() {
        // %q 会把不可见的零字节显示为 \x00，便于确认它没有消失。
        fmt.Printf("token=%q bytes=%v\n", scanner.Text(), scanner.Bytes())
    }
    if err := scanner.Err(); err != nil {
        // Scan 返回 false 还可能是 I/O 错误，不能只看循环结束。
        panic(err)
    }
}

这里得到的两个 token 会分别保留 A\x00B 与 C\x00D。原因不是 Scanner 对二进制做了特殊解析，而是 ScanLines 只寻找换行，并把换行本身从 token 中去掉。零字节没有被定义成行结束符，所以会原样留在 token 里。

零字节是内容，还是协议分隔符

排查到这里，最容易出现的误判是“既然能读取零字节，就可以直接用 Scanner 解析所有二进制数据”。实际上要先确认协议。若零字节只是字段内容，默认 ScanLines 可以继续使用；若格式规定字段由 NUL 分隔，就必须把分隔规则明确交给 Scanner。

下面这个 SplitFunc 每次寻找一个零字节，并把它之前的内容交给调用方。没有找到完整分隔符时返回 (0, nil, nil)，让 Scanner 继续读取；到达 EOF 后，如果还有最后一段数据，则把它作为最后一个 token 返回。

package main

import (
    "bufio"
    "bytes"
    "fmt"
    "strings"
)

func splitNUL(data []byte, atEOF bool) (advance int, token []byte, err error) {
    // NUL 是协议分隔符时，分隔符本身不放入 token。
    if i := bytes.IndexByte(data, 0); i >= 0 {
        return i + 1, data[:i], nil
    }
    if atEOF && len(data) > 0 {
        // 最后一段没有 NUL 结尾，也要交付给调用方。
        return len(data), data, nil
    }
    // 当前缓冲区还不完整，请 Scanner 继续向 Reader 取数据。
    return 0, nil, nil
}

func main() {
    input := "user\x00role\x00active"
    scanner := bufio.NewScanner(strings.NewReader(input))
    scanner.Split(splitNUL)

    for scanner.Scan() {
        // Text 只负责把当前 token 转成字符串，不会补回分隔符。
        fmt.Printf("field=%q\n", scanner.Text())
    }
    if err := scanner.Err(); err != nil {
        // 自定义 SplitFunc 的错误也通过 Err 读取。
        panic(err)
    }
}

这段代码适合“字段较小、分隔规则稳定”的协议。需要注意相邻的两个 NUL 会产生一个空 token；如果协议还要求保留末尾空字段，就要额外设计最后一个分隔符的语义，不能把示例直接当成通用 CSV 解析器。

真正让 Scanner 失败的通常是 token 大小

零字节本身没有触发错误，超长 token 才更常见。Scanner 会把数据交给 SplitFunc；如果一直没有遇到分隔符，内部缓冲会持续增长，超过允许的 token 大小时扫描停止，并通过 Err 暴露错误。可以在开始扫描前调用 Buffer 调整上限，但它不是无限内存方案。

package main

import (
    "bufio"
    "fmt"
    "strings"
)

func main() {
    input := strings.Repeat("x", 128*1024) + "\n"
    scanner := bufio.NewScanner(strings.NewReader(input))
    // 预留可复用缓冲，并把单个 token 上限设为 256 KiB。
    scanner.Buffer(make([]byte, 0, 32*1024), 256*1024)

    if scanner.Scan() {
        // 只有在 token 确实读出后，才使用 Text 或 Bytes。
        fmt.Println("token length:", len(scanner.Bytes()))
    }
    if err := scanner.Err(); err != nil {
        // 上限不足时这里能看到扫描停止的原因。
        fmt.Println("scan error:", err)
    }
}

还有一个容易被忽略的边界：scanner.Bytes() 返回的切片可能指向 Scanner 的内部缓冲，下一次 Scan 后内容可能被覆盖。如果要把 token 放入队列、跨 goroutine 使用或长期保存，应立即复制；若只是当前循环内同步处理，才可以直接使用。

什么时候应该换成 bufio.Reader

我的判断标准是：如果数据是“按行或按小字段切分”，Scanner 的 API 简洁；如果 token 可能很大，或者需要精确掌握读取了多少字节、保留分隔符、连续执行多种读取操作，bufio.Reader 更合适。固定长度的二进制字段则应优先使用 io.ReadFull 一类按长度读取的方式。

这次排查的结论

bufio.Scanner 能读取包含零字节的数据，默认情况下 NUL 会留在 token 中，不会自动变成结束符。问题的核心是先确认分隔协议，再决定是否自定义 SplitFunc；同时给 token 设置合理的上限，并在保存 Bytes 结果时复制底层数据。

如果你的输入是小型、边界清楚的记录，Scanner 依然很方便；如果数据可能超长，或者是需要逐字节控制的二进制协议，尽早切换到 Reader 或定长读取，通常比不断调大 Scanner 缓冲更稳妥。

相关问题

Scanner 会自动删除零字节吗？

不会。默认 ScanLines 只处理换行及可选的回车，零字节会作为 token 内容返回。

自定义 SplitFunc 为什么要返回 0、nil、nil？

这表示当前数据还不足以组成完整 token，Scanner 应继续从 Reader 读取，而不是提前结束扫描。

调整 Buffer 后还会不会失败？

会。新上限只是允许更大的 token；如果单个 token 仍超过该上限，Scanner 依然会停止。没有明确上限或需要更细的读取控制时，应考虑 Reader。