Go bufio.Scanner 为什么读不完整长行：Buffer 上限、SplitFunc 与流式边界

不少写日志采集的朋友都遇到过这种情况：前面几行数据读得好好的，碰到一条超长的JSON日志之后程序就悄无声息停了，后面的内容全没读到。用 bufio.Scanner 时，这通常不是文件提前结束，而是单个 token 超过了 Scanner 的缓冲上限；如果只判断循环退出就认为任务完成，不额外检查 scanner.Err()，很容易把异常失败误判成“正常读完了”。

先用一条超长日志复现停止点

先别着急上来就改配置，写个最小复现案例，把问题和业务逻辑隔离开排查会快很多。下面的输入总共只有一行，但是长度超过了Scanner默认的缓冲阈值：

package main

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

func main() {
    longLine := strings.Repeat("x", 70*1024) + "\n"
    scanner := bufio.NewScanner(strings.NewReader(longLine))

    count := 0
    for scanner.Scan() {
        count++
        fmt.Println("line bytes:", len(scanner.Bytes()))
    }

    fmt.Println("lines:", count)
    fmt.Println("scan error:", scanner.Err())
    if scanner.Err() != nil && scanner.Err() != io.EOF {
        fmt.Println("input was not fully consumed")
    }
}

关键不是循环有没有进入后续分支，而是循环结束后返回的错误信息。典型输出会包含 bufio.Scanner: token too long，此时当前这条长行没有作为完整 token 交给调用方处理。Scanner遇到token过大的情况会直接停止，后续的输入也不会自动继续拼接成业务需要的记录。

Buffer、MaxScanTokenSize 和 ScanLines 到底谁限制了长度

这个问题常被一句“Scanner 有 64 KB 限制”带过，但实际限制逻辑涉及三个不同的角色：

这里提到的“最大 token”不是业务层的字段长度校验。它只会判断Scanner能不能把当前分隔出来的单位装进自己的缓冲区；就算你把上限调到4 MB，后续仍然要自行判断单条日志、单个CSV字段是否真的允许这么大的尺寸。

最小修复：在扫描开始前设置上限

如果输入协议明确约定“一条记录对应一行”，而且业务侧可以接受合理的最大行长，那你可以在创建完Scanner之后立刻设置Buffer参数：

scanner := bufio.NewScanner(reader)
maxLineSize := 2 * 1024 * 1024
scanner.Buffer(make([]byte, 64*1024), maxLineSize)

for scanner.Scan() {
    line := scanner.Text()
    if len(line) == 0 {
        continue
    }
    handleLine(line)
}
if err := scanner.Err(); err != nil {
    return fmt.Errorf("read input: %w", err)
}

第二个参数是硬上限，不是“希望Scanner尽量分配多少内存”的软提示。如果某一行数据超过了你设置的2 MB，Scanner仍会主动停止；这个失败本身是有价值的，它能阻止一条异常超大的输入无限制进入后续解析逻辑。

调用顺序要固定：先创建Scanner实例，接着调用 Buffer 和 Split 完成配置，最后才启动扫描循环。扫描已经开始之后再调整这些配置方法，轻则达不到预期效果，重则直接触发运行时异常。

改 SplitFunc 不能绕过 token 上限

SplitFunc 决定“按什么规则切分token”，但它不会让Scanner获得无限的内存容量。默认的 ScanLines 适合处理换行分隔的记录；如果你的协议是逗号、空字节或者自定义帧格式，可以修改分割方式，但每个待产出的token仍然需要能装进Scanner的缓冲区里。

scanner := bufio.NewScanner(strings.NewReader("a|b|c|"))
scanner.Split(func(data []byte, atEOF bool) (int, []byte, error) {
    for i, b := range data {
        if b == '|' {
            return i + 1, data[:i], nil
        }
    }
    if atEOF && len(data) > 0 {
        return len(data), data, nil
    }
    return 0, nil, nil
})

for scanner.Scan() {
    fmt.Println(scanner.Text())
}

自定义分割函数要特别留意三个返回值：总共前进多少字节、返回什么内容作为token、是否携带错误。当输入数据还不完整时要返回 (0, nil, nil)，Scanner才会继续从底层读取新的数据；如果错误地返回空token却不移动读取指针，扫描器会在连续空结果之后直接终止。

什么时候应该换成 bufio.Reader

当单条记录可能非常大，或者你需要自己控制分块逻辑、分隔符规则和内存回收时机，bufio.Reader 往往是更直接的选择。它可以先用 ReadString、ReadBytes 或 ReadSlice 读取片段，再由业务层自行决定如何拼接和做大小限制。

reader := bufio.NewReaderSize(input, 64*1024)
var line []byte

for {
    part, isPrefix, err := reader.ReadLine()
    line = append(line, part...)
    if err != nil {
        if err == io.EOF && len(line) > 0 {
            handleLine(string(line))
        }
        if err != io.EOF {
            return err
        }
        break
    }
    if !isPrefix {
        handleLine(string(line))
        line = line[:0]
    }
}

ReadLine 返回 isPrefix 时，说明当前读取到的这一行还没有结束，调用方可以累计多个片段并自行设置总长度上限。这个写法需要额外实现拼接和超限保护的逻辑，但边界条件会更透明；不要为了逃避Scanner的报错，就毫无上限地追加内存。

扩展实验：把三个边界写成测试

最值得保留的不是某个固定的数值，而是针对边界场景的测试用例。至少覆盖刚好能读取的行、超过上限的行、没有换行但以EOF结尾的输入，以及自定义分割函数遇到不完整片段的情况。

func readOne(input string, max int) error {
    scanner := bufio.NewScanner(strings.NewReader(input))
    scanner.Buffer(make([]byte, 8), max)
    for scanner.Scan() {
        _ = scanner.Bytes()
    }
    return scanner.Err()
}

func main() {
    fmt.Println(readOne(strings.Repeat("a", 20)+"\n", 32))
    fmt.Println(readOne(strings.Repeat("a", 40)+"\n", 32))
}

如果第二个测试用例返回token过大的错误，说明你设置的限制确实生效了。生产代码还应该把这个错误转成可观测的计数或者日志字段，例如 input_line_too_large，这样才能快速分辨是上游数据本身异常，还是你设置的上限本来就太小了。

常见误区与相关问题

为什么 Scanner 循环结束后没有自动报错？

错误不会通过循环条件直接暴露出来，必须在循环结束后主动调用 scanner.Err() 才能拿到。忽略这个检查步骤，会直接把“读取出错”当成“正常读取完成”。

Buffer 的第二个参数应该设多大？

按协议约定的最大记录大小设置，同时给换行符、编码和后续解析的开销留出余量；不要只按当前样本的平均长度估算数值。

把 Scanner 的上限设成很大安全吗？

不一定。上限越大，异常输入可能占用的内存就越多。对来自网络或者不可信文件的输入，最好同时做总大小、单条记录大小和超限后的停止策略多层防护。

自定义 SplitFunc 后还需要检查 Err 吗？

需要。SplitFunc 自身返回的错误、底层读取错误和token过大异常，都会通过 Err 暴露出来，不能因为切分逻辑是自定义的就省略这步复查。

最后的选择标准

如果输入是一行一条记录，行长上限明确，优先使用 Scanner 并在扫描前设置好 Buffer；如果记录大小不可预测、需要分块拼接或者协议边界由业务自行控制，用 Reader 会更合适。无论选哪一个方案，都把“读到正常EOF”和“中途失败”两种情况分开记录，长行导致的静默丢数据问题就不会再反复出现。