Go bufio.Scanner 为什么会提前停止：ErrTooLong、SplitFunc 与错误检查

日志导入程序里，最容易被忽略的一行往往是 for scanner.Scan()。循环突然结束时，文件可能根本没有读完：一行超过 Scanner 的 token 上限、SplitFunc 没有继续推进输入，或者底层读取已经出错，都可能让 Scan 返回 false。真正的判断必须放在循环后检查 scanner.Err()，并根据数据大小选择合适的缓冲策略。

先复现：文件还有内容，Scan 却已经停了

先准备一条明显长于普通日志行的记录，再运行下面的程序。它故意使用默认配置，观察循环后的错误，而不是只打印已经读到的行数。

package main

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

func main() {
    input := strings.NewReader(strings.Repeat("x", 100000) + "\nsecond line\n")
    scanner := bufio.NewScanner(input)
    count := 0
    for scanner.Scan() {
        count++
        fmt.Println("token length:", len(scanner.Bytes()))
    }
    fmt.Println("tokens:", count)
    fmt.Printf("scan error: %v\n", scanner.Err())
}

这里通常会看到 bufio: token too long。如果把最后一行 Err 检查删掉，程序看起来像是“正常读完了”，但第二行从未被处理。这是 Scanner 最常见的静默误判来源。

默认上限解决什么问题，不能解决什么问题

Scanner 会把输入切成 token，默认的 ScanLines 把一行作为一个 token。它内部使用缓冲区逐步读取；当下一个 token 需要的空间超过允许上限时，扫描会停止并保留错误。这个限制是保护机制，不是文件大小限制：小文件里同样可以藏着一行超长文本。

如果业务能确定单行上限，可以在开始扫描前设置缓冲区：

scanner := bufio.NewScanner(r)
buf := make([]byte, 64*1024)
scanner.Buffer(buf, 1024*1024) // 初始 64 KiB，单 token 上限 1 MiB
for scanner.Scan() {
    line := scanner.Text()
    // 处理 line
}
if err := scanner.Err(); err != nil {
    return fmt.Errorf("scan input: %w", err)
}

第二个参数是硬上限，不是“希望大小”。把它设置成几百 MB 之前，先估算最坏内存占用；如果输入来自网络，还要同时设置请求体大小和超时边界。上限提高后仍然要验证单行是否符合业务格式，不能让一条异常记录拖垮整个导入任务。

SplitFunc 的三个返回值决定扫描能否前进

自定义分隔规则时，返回值的语义比函数名更重要：返回一个 token 表示已经找到结果；返回 nil, 0, nil 表示需要更多数据；返回错误表示扫描失败。若输入已经足够，却反复返回零推进的“继续等待”，扫描器就无法找到下一个边界。

func splitPipe(data []byte, atEOF bool) (advance int, token []byte, err error) {
    if i := bytes.IndexByte(data, '|'); i >= 0 {
        return i + 1, data[:i], nil
    }
    if atEOF && len(data) > 0 {
        return len(data), data, nil
    }
    return 0, nil, nil
}

这个规则把竖线当分隔符，并在 EOF 时把最后一段无分隔符内容交出来。注意：找到分隔符时 advance 要跨过分隔符；只返回 token、不推进输入，会导致重复扫描或最终报错。

把正常结束、超长和底层错误分开记录

推荐把扫描结果写成显式状态，而不是把 false 直接映射成“完成”。下面的结构适合导入脚本或后台任务使用：

for scanner.Scan() {
    if err := handle(scanner.Bytes()); err != nil {
        return fmt.Errorf("handle record %d: %w", count, err)
    }
    count++
}
if err := scanner.Err(); err != nil {
    return fmt.Errorf("read record after %d items: %w", count, err)
}
return nil

如果需要统计超长行，可以用 errors.Is 或错误文本做分类时保持谨慎，并把原始错误保留在日志里。更重要的是不要在错误后继续提交“导入成功”的汇总状态；任务应落到可重试或人工检查的失败状态。

什么时候该换成 bufio.Reader

Scanner 的优点是接口小、按 token 处理方便，但它要求每个 token 有可接受的上限。如果协议允许任意长度的行，或者你需要区分“读到分隔符前已经读取了多少字节”，bufio.Reader.ReadString、ReadBytes 或分块读取通常更合适。换工具不是为了绕过限制，而是把内存和错误策略交给业务。

上线前至少做三组输入：普通多行文本、恰好达到上限的行、超过上限的行；再补一组底层 Reader 返回错误的测试。每组都记录处理条数、最后一个 token 和最终错误，才能确认“停止”发生在预期位置。

相关问题

Scan 返回 false 就一定是 EOF 吗？

不一定。正常 EOF 时 Err 通常为 nil，但超长 token、底层读取失败或 SplitFunc 返回错误也会让 Scan 停止，所以必须检查 scanner.Err()。

Buffer 应该设置多大？

按业务允许的最大 token 设置，并给异常输入留出明确失败路径。网络输入不要只放大 Scanner 上限，还应限制请求体和任务总耗时。

自定义 SplitFunc 为什么会卡住？

常见原因是数据已经足够却返回 0, nil, nil，或者返回 token 时 advance 没有跨过已消费的字节。把分隔符、EOF 和空 token 分别写测试，通常很快能定位。

发布前的检查清单

检查 Scanner 代码时，先确认 token 的真实上限，再核对是否在循环后检查 Err；使用自定义 SplitFunc 时，逐个验证返回 token、等待更多数据和返回错误三条路径。最后用超长行与模拟 I/O 错误跑一次回归。这样处理后，for scanner.Scan() 就不再承担它没有表达能力的“任务成功”含义。