Go bufio.Scanner 为什么返回 token too long

Go 的 bufio.Scanner 返回 token too long，通常不是输入流损坏，而是默认的按行切分遇到了过长记录。默认 ScanLines 把一整行视为一个 token，MaxScanTokenSize 为 64 * 1024 字节，而且实际可用空间还要容纳换行等边界数据。

如果业务能给出合理的最长行长，就在第一次 Scan 前调用 Scanner.Buffer；如果记录长度不可控，直接改用 bufio.Reader，不要把 max 无限制调大。

官方参考：https://pkg.go.dev/bufio

先看懂 token too long 到底超了什么

Scanner 的默认 split 函数是 ScanLines。因此一条没有换行的长 JSON、堆栈字段、SQL 文本或日志扩展字段，都可能被当成一个超大 token。扫描超过缓冲上限后会停止，Scan 返回 false，再通过 Err 看到 bufio.Scanner: token too long。

这个停止是不可恢复的：官方文档明确提醒，扫描停止时底层 reader 可能已经越过最后一个完整 token。也就是说，不能先忽略错误，再期待下一轮 Scan 继续从原位置读。先把问题归类清楚，再决定调大上限还是换读取器。

固定上限时，在 Scan 前扩大 Scanner 缓冲

当你知道单行最多约 1 MiB，可以为 Scanner 设置一个有边界的最大值。第二个参数是允许分配的最大缓冲，不是建议每次都分配这么多；第一参数给出初始缓冲，二者都应结合输入规模和并发量设定。

package main

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

func readLines(input string) error {
	// 用可复用的初始缓冲承接普通行，避免每次从很小的容量开始扩张。
	scanner := bufio.NewScanner(strings.NewReader(input))
	// Buffer 必须在第一次 Scan 前调用；1 MiB 是本示例允许的单 token 上限。
	scanner.Buffer(make([]byte, 64*1024), 1024*1024)
	scanner.Split(bufio.ScanLines)

	for scanner.Scan() {
		// Text 返回当前 token；业务代码应在这里完成解析或入队。
		fmt.Println(scanner.Text())
	}
	// Scan 返回 false 既可能是 EOF，也可能是 token 太长或底层读取错误。
	if err := scanner.Err(); err != nil {
		return fmt.Errorf("scan input: %w", err)
	}
	return nil
}

配置后仍然要检查 Err。如果最长记录超过 1 MiB，错误仍会出现；这不是把上限调成一个更大的“万能数”就能解决的问题。高并发服务还要把最大值乘以并发读取数估算内存峰值。

固定上限用 Scanner，不确定长度用 Reader

如果输入来自用户、外部接口或格式不稳定的日志，单条记录可能远大于预估值。此时 bufio.Reader.ReadString 会持续读取到分隔符，调用方可以在拿到完整记录后处理；遇到 EOF 时也能根据已经读到的内容决定是否消费最后一条没有换行的记录。

package main

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

func readUnboundedLines(r io.Reader, consume func(string) error) error {
	// Reader 适合长度不可控的记录；这里的大小只影响读取颗粒度，不是整行上限。
	reader := bufio.NewReaderSize(r, 64*1024)
	for {
		line, err := reader.ReadString('\n')
		if len(line) > 0 {
			// 去掉分隔符，保留最后一条没有换行的有效记录。
			line = strings.TrimSuffix(strings.TrimSuffix(line, "\n"), "\r")
			if consumeErr := consume(line); consumeErr != nil {
				return fmt.Errorf("consume line: %w", consumeErr)
			}
		}
		if err != nil {
			// EOF 只表示输入结束；其他错误必须交给上层处理。
			if errors.Is(err, io.EOF) {
				return nil
			}
			return fmt.Errorf("read line: %w", err)
		}
	}
}

这个方案的代价是调用方要自己承担单条记录的内存与处理策略，但它不受 Scanner 的 token 上限约束，也更适合需要分段、重试或精细处理读取错误的场景。

配置时的边界与排查清单

排查时按四步走：先打印或统计单条记录的字节长度；确认是否使用默认的 ScanLines；检查 Buffer 是否早于第一次 Scan；最后确认循环退出后确实读取了 Scanner.Err。不要只把 64*1024 改成一个很大的数字，因为并发量、异常输入和内存峰值会把问题推迟到线上。

相关问题

Scanner.Buffer 的 max 是 token 的精确长度吗？

它是 Scanner 可分配缓冲的最大值，实际 token 上限还要受分隔符和内部扫描边界影响，因此不要把 max 当成无条件可用的精确字符数。

token too long 出现后还能继续 Scan 吗？

不能把它当成可跳过的普通记录错误。Scanner 会停止且底层 reader 可能已经前进；需要更强恢复或超长记录处理时，应从设计上改用 bufio.Reader。