Go bufio.Scanner.Buffer 怎么读取超长文本行

我第一次遇到这个问题，是在导入一份按行存储的 JSON 日志：绝大多数记录只有几 KB，偏偏有一条把完整调用链和请求体都塞进了同一行。代码没有崩溃，scanner.Scan() 却提前返回了 false。直到检查 scanner.Err()，才看到 token 过长。解决它不只是“把数字调大”，而是先确认单行上限、并发量和失败策略，再决定是否继续使用 Scanner。

本文依据 Go 标准库 bufio 文档说明，参考地址：https://pkg.go.dev/bufio。

一、先看负载：默认 64 KiB 为什么会不够

Scanner 默认使用 ScanLines，每次返回一行并去掉行尾的 \r?\n。标准库常量 MaxScanTokenSize 是 64 * 1024，但官方文档也特别说明：缓冲区还可能需要容纳换行符，因此真正能接受的 token 可能略小于这个数字。

这类问题常见于单行 JSON、压缩后展开的事件、证书内容、超长 CSV 字段和聚合日志。我的判断习惯是先问三个问题：正常行的 P99 大小是多少？异常行最大允许多少？同一时间会有多少个 Scanner 工作？这三个答案决定上限，而不是“机器还有多少内存”。

Buffer 接收两个参数：buf 是起始缓冲区，内容会被忽略；max 是扫描期间允许分配的最大缓冲区大小。最大 token 必须小于 max 与 cap(buf) 两者中的较大值。如果 max ，扫描会只使用这块缓冲区，不再为扩容分配内存。

二、约束条件：Buffer 必须在第一次 Scan 前设置

下面是一份可直接放进命令行程序的完整写法。这里把初始缓冲区设为 64 KiB，把单行上限设为 4 MiB。初始值负责常见行，上限负责少量异常但仍然合法的长行；它们不必相等。

package main

import (
	"bufio"
	"fmt"
	"io"
	"os"
)

func scanLongLines(r io.Reader, maxLineBytes int) error {
	if maxLineBytes 

有两个细节很值得保留。第一，Buffer 不能在扫描开始后调用，否则会触发 panic。第二，Scanner.Bytes() 返回的底层数组可能在下一次 Scan 时被覆盖；如果要把某行放进异步队列或长期保存，应在当前循环中复制：

saved := append([]byte(nil), scanner.Bytes()...)
// saved 拥有独立底层数组，可以安全交给后续协程。

三、方案对比：什么时候不该继续放大 max

对于“最大 4 MiB 的 JSON 行”这种边界明确的输入，我会继续使用 Scanner.Buffer，因为循环简洁，按行语义清楚。但如果输入来自不受信任的客户端，单行可能无限增长，把上限改成 1 GiB 并不稳妥：它只是把失败推迟到更昂贵的位置。

官方文档指出，Scanner 在 EOF、首个 I/O 错误或 token 大到无法放入缓冲区时会不可恢复地停止，而且底层 Reader 可能已经越过最后一个成功 token 很远。需要更强错误控制、处理大 token，或者要在同一个 Reader 上连续进行多段扫描时，应使用 bufio.Reader。

四、推荐架构：把大小上限当成输入契约

在日志导入、消息消费和文件解析里，我更推荐把“单行最大长度”放进输入契约，而不是散落在某个 make 调用里。比如协议规定单条事件不超过 2 MiB，代码可以留少量余量，把 Scanner 上限设为 3 MiB；监控则记录实际行长、超限次数与来源。这样调大上限有业务证据，调小时也知道会影响谁。

一个实用配置可以分成三层：

• 初始缓冲区：覆盖大多数正常行，例如 64 KiB，减少常见路径的额外分配。
• 最大 token：略高于协议允许的最大行，并把换行符等额外空间考虑进去。
• 进程级预算：用最大并发 Scanner 数乘以潜在缓冲区，检查峰值是否在可接受范围内。

举例说，单个 Scanner 的上限是 8 MiB，并不代表创建后立刻占满 8 MiB；它会从初始缓冲区开始，必要时扩容。但当大量输入同时出现超长行时，峰值仍可能接近“并发数 × 上限”，所以并发限制和上限必须一起设计。

五、风险点：几个容易被忽略的坑

• 只写循环，不看 Err：Scan() 返回 false 不等于一定读完，token 超限和 I/O 错误也会走到这里。
• 把 max 当成最大文本字符数：参数按字节计算，UTF-8 中文字符通常占多个字节；容量规划应基于字节。
• 在 Scan 之后调用 Buffer：这会 panic，配置必须在扫描开始前一次完成。
• 长期保存 Bytes：底层数组可能被下一次扫描覆盖，需要保留时应复制。
• 用极大上限代替输入治理：外部输入没有边界时，过大的 max 会放大内存风险；这时应改用 Reader 并实现累计长度限制或分块策略。

六、落地清单

• 统计真实行长分布，明确业务允许的最大单行字节数。
• 在第一次 Scan 前调用 Buffer，初始容量与最大容量分开设置。
• 循环结束后检查 scanner.Err()，把超限与普通 I/O 错误纳入日志和指标。
• 如果要跨循环保存 scanner.Bytes()，先复制。
• 用“最大并发数 × 最大 token”估算极端内存占用。
• 单行无法设定可信上限或需要可恢复错误控制时，改用 bufio.Reader。

相关问题

Buffer 的 max 会立即分配同样大的内存吗？

不会。Scanner 先使用提供的初始缓冲区，必要时再增长到允许范围；但大量并发长行仍会推高峰值内存。

为什么设置 64 KiB 仍可能读不了接近 64 KiB 的一行？

因为缓冲区还可能需要容纳换行符等数据，官方文档明确说明实际最大 token 可能小于 MaxScanTokenSize。

Scanner 超限后能否调大 Buffer 再继续？

不能把它当作可靠恢复方案。扫描开始后调用 Buffer 会 panic，而且超限停止时底层 Reader 可能已经向前读取。需要恢复控制时，应从一开始就选择 bufio.Reader 或重新建立可定位的输入源。