Go bufio.Scanner 怎样调整单次 token 的最大长度

如果 Go 的 bufio.Scanner 读取长行时出现 bufio.Scanner: token too long，通常不是输入流坏了，而是单个 token 超过了 Scanner 当前允许的缓冲上限。解决方式是在第一次调用 Scan 之前调用 Buffer，显式给出初始容量和最大容量；扫描结束后再通过 Err 判断是否真的失败。

最常用的写法是 scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)，但第二个参数不是“保证每行都能读到”的承诺：Scanner 仍会因为换行等分隔字节、整数溢出或输入超过上限而停止。若输入长度本来就不适合设置上限，应改用 bufio.Reader。

先确认默认上限和失败信号

NewScanner 默认使用 ScanLines，并把最大 token 缓冲尺寸设为 MaxScanTokenSize。Go 官方文档当前将这个常量定义为 64 KiB；源码也说明实际可容纳的 token 可能更小，因为缓冲区还可能需要容纳换行符等边界字节。

因此，只有把 Scan 循环写完还不够。循环结束后要检查 scanner.Err()：如果返回 nil，可能是正常 EOF；如果返回 bufio.ErrTooLong，就是 token 达到了上限；其他错误则应按输入源的 I/O 失败处理。

package main

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

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

	// 预留 64 KiB 的初始容量，最多允许 Scanner 扩展到 1 MiB。
	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)

	for scanner.Scan() {
		// Bytes 只在下一次 Scan 前可靠；需要长期保存时要复制。
		fmt.Println("token bytes:", len(scanner.Bytes()))
	}

	if err := scanner.Err(); err != nil {
		// 先区分 token 上限，再处理普通读取错误。
		if errors.Is(err, bufio.ErrTooLong) {
			fmt.Println("单个 token 超过 1 MiB 上限")
			return
		}
		fmt.Println("读取失败:", err)
	}
}

Buffer 应该放在 Scan 前调用

Scanner.Buffer(buf, max) 有两个作用：cap(buf) 提供初始缓冲能力，max 限制 Scanner 后续最多可以分配到的缓冲大小。buf 中已有的内容会被忽略，所以通常用 make([]byte, 0, capacity) 表达“只关心容量”的意图。

调用顺序很重要。官方文档明确指出，扫描已经开始后再调用 Buffer 会 panic。也就是说，下面的配置必须出现在第一次 Scan 之前，不能在扫描到一条长记录后临时补救：

scanner := bufio.NewScanner(reader)

// 先设置上限，再开始扫描；max 要结合单条输入的业务上限决定。
scanner.Buffer(make([]byte, 0, 32*1024), 2*1024*1024)

for scanner.Scan() {
	line := scanner.Text()
	// 这里处理当前行，下一次 Scan 可能覆盖 Scanner 的内部缓冲。
	_ = line
}

// 循环结束后统一读取错误，不能只看 Scan 返回 false。
if err := scanner.Err(); err != nil {
	return
}

怎样理解 max、cap 和实际可读长度

这三个量容易被混成一个概念：

如果 max ，Scanner 可以只使用传入的缓冲区而不再分配；如果 max 大于初始容量，Scanner 会在需要时扩大缓冲区，直到达到上限。默认的内部缓冲区会从较小的起始容量开始增长，因此给出合理的初始容量可以减少扩展次数，但也会提高每个 Scanner 的初始内存占用。

还要留出分隔符空间。以 ScanLines 为例，一行的 token 与行尾换行可能同时出现在内部缓冲区中，所以“最大行长”等于 max 并不意味着一定成功。业务上若允许 1 MiB 的行，通常应把 max 设得略大，并继续对输入做长度和资源预算。

超长 token 怎么处理，Bytes 为什么要及时复制

Scanner 的定位是方便地逐 token 扫描，而不是在 token 超限后暂停、提高上限再从原位置继续。官方说明指出，token 太大时扫描会不可恢复地停止，并且底层 reader 可能已经向前读取了超过最后一个 token 的数据。因此，遇到 ErrTooLong 后不应复用同一个 Scanner 期待无损续读。

另外，Bytes 返回的是最近一次扫描得到的切片，底层数组可能在下一次 Scan 时被覆盖；Text 返回字符串则适合直接使用，但如果要把二进制或原始字节存入队列，应显式复制：

func collect(scanner *bufio.Scanner) ([][]byte, error) {
	var queue [][]byte
	for scanner.Scan() {
		// 复制当前 token，避免下一次 Scan 覆盖底层数组。
		owned := append([]byte(nil), scanner.Bytes()...)
		queue = append(queue, owned)
	}
	if err := scanner.Err(); err != nil {
		// 超长、底层 I/O 错误都在这里统一收口；不要忽略非 nil 错误。
		return nil, err
	}
	return queue, nil
}

生产代码还应给 max 设置可解释的业务上限，而不是为了“先跑起来”直接传一个极大的整数。上限过大可能让恶意或异常输入占用过多内存；上限过小又会把合法记录误判为失败。可以把上限、输入类型和错误指标一起记录下来，方便后续调整。

什么时候应该换成 bufio.Reader

如果单条输入的长度不可预测，或者你必须在长记录中分段处理、保留未消费数据、准确控制读取位置，就不应只靠增大 Scanner.Buffer。Go 官方源码对 Scanner 的说明也建议：需要更强的错误控制、处理大 token，或需要在同一个 reader 上进行连续扫描时，考虑 bufio.Reader。

一个简单的选择表如下：

排查 token too long 的运行手册

1. 触发信号：确认 scanner.Scan() 提前返回 false，并记录 scanner.Err() 的具体错误。
2. 快速判断：检查是否使用了默认上限，单行或单字段是否可能超过 64 KiB，以及分隔符是否也需要占缓冲空间。
3. 处理步骤：在第一次 Scan 前调用 Buffer，把初始容量和最大容量设置为有依据的数值。
4. 回滚路径：如果调大上限后内存占用或延迟不可接受，恢复较小上限并改用 Reader 分段处理，而不是继续把 max 调大。
5. 告警确认：区分 ErrTooLong、底层读取错误和正常 EOF，避免把正常结束误报成故障。
6. 复盘项：记录输入类型、最大合法长度、实际拒绝长度和每个 Scanner 的并发量，下一次再调整容量预算。

总结

调整 Go bufio.Scanner 的单次 token 长度，关键不在于修改一个神秘的全局常量，而是把 Buffer 放在第一次 Scan 之前，并同时理解初始 cap、最大 max 和分隔符空间。扫描结束必须检查 Err；遇到超长 token 后不要假设 Scanner 能从原位置无损恢复。输入不适合设定明确上限时，bufio.Reader 往往是更稳妥的边界。

相关问题

Scanner.Buffer 的 max 越大越好吗？

不是。max 越大，异常输入可以占用的内存上限也越高。应按单条合法输入的业务边界设置，并给换行或其它分隔字节留出空间。

为什么 Scan 返回 false 还要调用 Err？

因为 false 既可能表示正常 EOF，也可能表示 I/O 错误、SplitFunc 错误或 token 超过缓冲上限。只有 Err 返回 nil 时，才能把结束当作无错误完成。

Scanner 能在 ErrTooLong 后继续读取吗？

不建议。Scanner 在 token 过大时是不可恢复地停止，reader 也可能已经向前读取了额外数据；需要恢复和分段控制时应从设计上改用 Reader。