原文件是有效的 UTF-8,为什么分块读取会出现 �?
日志下载后用文本编辑器打开,汉字和表情符号都正常。换成一个边下载边显示的程序,偶尔却在某一块的末尾看到 �。先把收到的原始字节拼起来验证。如果完整内容可以严格按 UTF-8 解码,而同一份字节分块后不能,通常可以从代码里找到原因。程序把每个读取块交给一个独立的解码过程,解码器便把块尾当成了整份输入的末尾。
本次实验用同一份短文本分别做两种处理。逐块替换错误会把两个完整字符变成五个替换字符。让同一个解码器跨块保留状态,就能还原原文。真正缺了字节的输入仍然会触发错误,只是错误发生在已经有依据判定它无效的时候。
读到几字节,由读取端决定
UTF-8 用一个到四个字节表示一个 Unicode 标量值。ASCII 字符只占一个字节,所以只用英文字母测试时,即使每次独立解码也很难暴露问题。对于多字节序列,第一个字节提供长度线索,后面还需要符合规则的续字节。一个块刚好结束在序列中间时,光凭当前字节无法判断余下部分是下一次才会到,还是整份输入已经截断。RFC 3629 的 UTF-8 编码定义
实验输入是 A雨🍊B。其中 A 和 B 各占一个字节,雨 占三个,🍊 占四个。把原始字节按三个一组切开,第一块在 雨 的第二个字节后结束,第二块在 🍊 的第二个字节后结束。三个块按顺序拼回去,仍然是原来的九个字节。切分没有删去任何内容。
| 输入顺序 | 收到的十六进制字节 | 分别解码并替换错误 | 增量解码输出 | 等待后续字节 |
|---|---|---|---|---|
| 第一块 | 41 e9 9b | A� | A | e9 9b |
| 第二块 | a8 f0 9f | �� | 雨 | f0 9f |
| 第三块 | 8d 8a 42 | ��B | 🍊B | 无 |
第一块到来后,增量解码器交付已有的 A,把 e9 9b 留在内部。下一块开头的 a8 补齐 雨,但后面又遇到半个表情符号,所以只交付 雨。最后一块到来时,表情符号和后面的 B 都已完整。输出的文字片段与输入块在时间上相对应,但其内容可以来自两个块。一个输入块也完全可能产生空输出。
固定增大读取块只能改变哪一个位置被切开。只要边界仍以字节数决定,某个输入就可能刚好把字符放在边界上。要让测试可靠,可以像脚本一样主动构造边界。脚本遍历了这九个字节的 10 种两段切法,包括首尾的空段,也测试了从单字节到整段的 9 种固定块长。所有切法都还原了同一份文本。
让一个解码器跟随一份字节流
Python 标准库提供 codecs.getincrementaldecoder。先按已知编码创建一次实例。每来一块字节,就将它交给这个实例,并让它知道后面可能还有数据。确认输入结束后,用空字节块结算。调用中是否产生文字取决于当前字节和实例保留的状态。相同的代码也可以在收到结果后立刻写入界面或供给下一个处理步骤,无须等到整份文本下载完。Python 的增量解码接口
import codecs
def decode_chunks(chunks, encoding="utf-8", errors="strict"):
decoder = codecs.getincrementaldecoder(encoding)(errors=errors)
for chunk in chunks:
yield decoder.decode(chunk, final=False)
yield decoder.decode(b"", final=True)
这段函数和实验脚本中的实现相同。一份连续字节流有一个解码器,彼此独立的文件或响应各自创建实例。若用同一个实例交替处理两个来源,上一份输入留下的字节可能被带到另一份,连错误位置也会难以解释。反过来,如果上游协议明确规定每条消息自身已包含完整文本,就可以在消息边界结算。决定实例何时建立和何时结束的是输入的边界,函数被调用多少次只是程序的传递方式。
也可以先把所有块拼成完整字节串再解码。如果应用本来就要等全量输入才能处理,这是直接的做法。若文件已经通过 Python 的文本模式打开,可以让它内部的文本解码层处理字节边界。实验还用 TextIOWrapper 对同一份内容反复调用 read(1),读到的是 A、雨、🍊、B 四段文本。此时接口的长度单位已是 Python 字符串里的码点,一个调用可以在内部读取多个字节。Python 的二进制流与文本流
只有确认结束,才能判断末尾是不完整序列
实验先输入一块字节,内容是 OK 加上表情符号的前两个字节 f0 9f。普通调用先返回 OK,因为序列仍有可能被补齐。以 final=True 结算时,严格模式为这两个未完成的字节报出 unexpected end of data。替换模式则在结算时返回一个 �。若在结算之前就接到 ASCII 字符 X,它已经不可能是预期的续字节,严格模式会在这次调用中报出 invalid continuation byte。
脚本也在第一块后插入一个空输入。只要传入时保留 final=False,那一次就只是输出空字符串,原先保存的两字节继续等待。真实读取接口如何表示结束,由接口本身规定。阻塞式文件读取可以用返回空字节串来判定读到末尾。若输入来自事件回调,则按该接口的结束事件结算。空的回调数据和真正的输入结束有不同的含义。
什么时候采用严格模式,取决于解码错误会造成什么后果。日志预览可以用替换字符保留其余可读内容,但若要导入配置或以文本作为记录键,替换后的值有可能变成另一个值。流式处理时还要注意,前缀可能已经交给下游,结尾才报错。如果整个导入要求完整成功,应用应当先暂存结果,等解码和解析都完成后再提交。严格解码器负责报错,调用方负责决定是否接受此前产生的内容。
无效序列还有第三种情形,错误在第一个字节就已经确定。实验把 c0 80 分两次送进解码器,第一次收到 c0 就报出 invalid start byte。这个字节序列曾被用作空字符的过长编码,有效的 UTF-8 只接受该标量值的最短表示 00。增量解码可以等待一个有希望完成的前缀,同时会拒绝已知无效的开头。遇到提前报错时,可以保留错误字节的十六进制表示来区分这两类输入。RFC 3629 的字节序列语法
看到界面上的 � 也不一定能反推是哪一步出了错。它可能是解码器替换错误时生成的,也可能本来就是原文的一部分。脚本把字面上的 � 编成 ef bf bd,拆成两块后用严格模式正常读回。同一个显示结果可以来自不同的原始字节。若只保存替换后的文本,排查时已经失去了区分它们所需的信息。可以把原始输入的相关片段和上下文留给诊断,再按业务需要生成方便阅读的预览。
字符可以完整,记录还没结束
实验把两个 JSON 对象写成换行分隔的文本,每条记录末尾都带换行。第一条消息包含汉字和表情符号,第二条消息里本身有一个换行,序列化后会变成 JSON 字符串内部的转义,因此不会占用记录分隔符。输入总长 33 字节,再按每块 2 字节送给解码器。解码得到的片段有时只到一条记录的中间,所以解析器另存一段待处理文本,见到换行才尝试解析对应行。最后拿到两个与输入相同的对象。
去掉最后一个换行再运行,UTF-8 解码仍然成功,实验的记录解析器却报告缺少结束符。这是示例明确选定的协议规则。若实际协议允许最终记录省略换行,结束时就要解析剩余文本。反之,若协议要求末尾必须有结束符,收到半条记录也不能当成正常结果。编码层负责从字节得到文本,记录层负责判断消息完成。两个层次各保留自己的未完成部分。
这个示例的解析器用于展示分界,待处理文本会累积到下一条换行。如果输入可能包含很长的单行,就需要在应用里定义单条记录的最大尺寸,并在超出限制时处理。如果要在界面上按用户感知到的字符做截断,组合重音或多个码点组成的表情也还需要额外考虑。增量 UTF-8 解码交付的是已经解码的码点,记录和显示有自己的边界。
另一个容易混淆的现象是文件开头的 BOM。脚本把签名的三个字节拆在三个输入块中,并在文本中间再放一次相同的字节。Python 的 utf-8 会把两处都解为 U+FEFF,utf-8-sig 则只跳过开头的一处。这个差别来自读取格式的约定。看到开头有这个字符时,先查输入格式是否把它定义为签名,再决定使用哪个解码器。Python 的 UTF-8 签名说明
如果记录层要报告错误位置,还应注明位置的单位。一段文本的开头可能先有几个单字节字符,再有多字节字符。此后第几个码点与第几个字节就会逐渐错开。要对照抓到的原始数据,可以先记下每块的起始字节位置。增量解码抛出的异常也可能引用前一块留下的字节,因此局部索引应结合解码器输入的上下文理解。
本次于 2026 年 11 月 14 日在 macOS 27.0.1、arm64、CPython 3.12.14 上运行。脚本只用标准库,以确定的字节切分复现实验,没有依赖网络传输时机。遇到类似问题时,可以保存出错时的字节和分块顺序,在本地先比较整段严格解码,再查跨块状态与结束处理。若整段也失败,还需要回查原始字节和上游声明的编码。
python3 utf8-stream-lab.py > report.json