← 返回首页

Python decode 的 errors 参数:五个策略,只有一种能原样写回

Python编码调试

一个 47 字节的小文件,我把它在五套脚本里过了五遍,回来的字节没有一个和原件相同——除了那一套用了 surrogateescape 的。

这不是边角案例。任何读日志、读 CSV、读第三方导出的程序,都会在某一刻拿到不合法的字节:GBK 系统导出的表格、被截断的 UTF-8 多字节字符、扫描枪吐出的二进制尾巴。Python 给了五个标准错误处理器,默认是 strict。于是最常见的改法是把它换成 ignore,让程序先跑通。

问题在于「跑通」和「数据还在」是两件事。ignore 让程序跑通的同时,把那个字节从结果里删掉了;replace 把它替换成 U+FFFD;backslashreplace 把它变成四个可打印字符;只有 surrogateescape 能把它原封不动地带回来,代价是这个字符串从此不能被普通方式写回去。

// FLOW_01坏字节进入程序后的四道关卡4 NODES01STEP_01拿到 bytes:文件、管道、套接字、子进程输出02STEP_02选编码:utf-8,还是本地代码页03STEP_03选 errors:五种错误处理器里挑一个04STEP_04决定回写:这次往返是否逐字节相同END_OF_FLOW
坏字节进入程序后的四道关卡 · 依据本文步骤自绘示意图
PythonLinuxJson
文中涉及的技术标识 · 图标来自 Simple Icons(CC0)

errors 参数管的只是「转换失败的那一瞬间」

官方 codecs 文档把这件事说得很清楚:errors 指定的是「按编码规则转换不了时怎么办」,默认值 'strict' 表示直接抛 UnicodeError 的子类。它不是编码选择器,也不校验你选的编码对不对——这一点后面会咬人。

方向也要分清楚。bytes.decode() 和 str.encode() 各有一套 handler:

反过来用会直接报错。我实际测试时把 namereplace 传给解码,拿到的是 TypeError: don't know how to handle UnicodeDecodeError in error callback,不是「不支持这个参数」那种友好提示。

同一串坏字节,五种策略的产出

样本取自真实故障现场的形状:b'caf\xe9 ok',7 个字节,第 4 个字节是 Latin-1 的 é,在 UTF-8 里不合法。

bad = b'caf\xe9 ok'
for h in ('strict', 'ignore', 'replace', 'backslashreplace', 'surrogateescape'):
    print(h, repr(bad.decode('utf-8', h)))

跑出来的五条结果,长度分别是 6、7、10、7:

策略结果字符数那一个字节去哪了
strict抛 UnicodeDecodeError—没进去
ignore'caf ok'6删掉了
replace'caf\ufffd ok'7变成替换符
backslashreplace'caf\\xe9 ok'10变成 4 个字符
surrogateescape'caf\udce9 ok'7变成 U+DC E9

注意 replace 和 surrogateescape 的字符数一样(都是 7),肉眼看上去都「没丢东西」。这是最容易误判的一处:字符长度对得上,不代表字节对得上。

往返测试:只有一种能逐字节改回去

解码完还得写回去,而写回去用哪个 handler 是另一个独立决定。四种解码策略乘三种编码策略,12 个组合里只有一个完全相同:

解码策略编码 strict编码 surrogateescape编码 backslashreplace
ignore少 1 字节少 1 字节少 1 字节
replace多 2 字节多 2 字节多 2 字节
backslashreplace多 3 字节多 3 字节多 3 字节
surrogateescape抛 UnicodeEncodeError完全相同多 5 字节

道理不难:U+DC80 到 U+DCFF 这一段是 PEP 383 专门留出来的「私货区」,官方文档的原话是「解码时把字节替换成 U+DC80 到 U+DCFF 的代理码位,用同一个 handler 编码时会变回同一个字节」。别的策略在解码那一刻就把原始字节的信息销毁了,后面无论怎么编码都补不回来。

落盘测试:谁在改你的文件大小

把 47 字节的样本(中文加两个坏字节)读进来再写出去,文件大小这样变:

策略回写后大小与原件相同
ignore45 B否
replace51 B否
backslashreplace53 B否
surrogateescape47 B是

replace 让文件变大,是因为 U+FFFD 编码成 UTF-8 要 3 个字节,替换 1 个坏字节净增 2 B。这类「文件每晚都在长胖」的怪现象,根因往往就是一个 errors='replace'。

surrogateescape 不是修复,是把报错推迟到下一站

surrogateescape 的解码结果里含代理码位,这种字符串在 UTF-8 下是非法的。官方文档的另一句提醒很到位:文件系统编码这一层才默认用 surrogateescape,普通文本编码不是。

于是同一个字符串,print() 可能没事(终端容错),一写文件就炸:

s = b'caf\xe9 ok'.decode('utf-8', 'surrogateescape')
s.encode('utf-8')                      # UnicodeEncodeError
s.encode('utf-8', 'surrogateescape')   # 正常,回到 b'caf\xe9 ok'

CSV 场景更隐蔽。我用 csv.writer 写两行,writerows 全程不报错,文本也对;等 encode 时才拿到:

UnicodeEncodeError: 'utf-8' codec can't encode character '\udce9' in position 14: surrogates not allowed

所以 surrogateescape 的正确用法是成对出现:open(..., errors='surrogateescape') 读,同一个 handler 写。只在一头用它,等于把异常搬到一个更难查的位置——这条经验和我之前梳理 CSV 记录边界 时的结论一致:newline='' 与 errors 都是「成对开关」,单边设置只会把问题推后。

backslashreplace 最像安全牌,其实是二次污染

它的产出是纯 ASCII:'caf\\xe9 ok'。这一步太讨喜了——str.isascii() 返回 True,写进 JSON、日志、数据库都不会再报编码错,校验层全绿。

代价在下一站。'price=\\xe9' 里的 \xe9 是四个可见字符,任何 int() 或 float() 都会拿到 ValueError: invalid literal for int() with base 10: '\\xe9'。更糟的是它会把 1 个字节写成 4 个字节,再编码时这 4 个字符又各自变成 1 个字节,一次转换把体积抬到原来的 4 倍,而且不可逆。

JSON 层:文件合法了,字段少了

同一份 b'{"id": 7, "name": "caf\xe9", "amount": 19.99}',五种策略过 json.loads 的结果:

策略name 字段JSON 是否合法
strict抛 UnicodeDecodeError—
ignore'caf'合法
replace'caf\ufffd'合法
backslashreplace抛 JSONDecodeError不合法
surrogateescape'caf\udce9'合法

两个反直觉的点。第一,backslashreplace 是唯一会让 JSON 解析失败的——\x 不是合法 JSON 转义,报错原文是 Invalid \escape: line 1 column 23 (char 22)。第二,ignore 之后 JSON 完全合法,schema 校验也会通过,只是 name 少了最后一个字符,金额照旧。下游看到的是一个「正常」的客户名。

subprocess 的 text=True:异常进了线程,stdout 变成 None

这条最容易让人以为程序没问题。子进程往 stdout 写了坏字节,父进程用 text=True 收:

r = subprocess.run([sys.executable, '-c', "import sys;sys.stdout.buffer.write(b'caf\xe9 ok')"],
                   capture_output=True, text=True)
print(r.returncode, r.stdout)

结果是 0 None。返回码 0,stdout 是 None(不是空字符串),主流程照常往下走。真正的异常被扔在读取线程里:

Exception in thread Thread-3 (_readerthread):
  File "subprocess.py", line 1615, in _readerthread
    buffer.append(fh.read())
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe9 in position 3

显式写 errors='strict' 结果一样;只有 errors='surrogateescape' 才拿回 'caf\udce9 ok'。text=True 默认就是 strict,它不会把解码失败升级成 CalledProcessError——这一点和我写 subprocess 七个静默失败 时的结论同源:子进程这一层的失败,默认都是「安静地少给你一点东西」。

Windows 的文件系统 handler 不是 surrogateescape

文档说文件系统编码失败时用 surrogateescape。这句话在 Windows 上要打折扣——本机实测 sys.getfilesystemencodeerrors() 返回的是 'surrogatepass',不是 'surrogateescape':

os.fsdecode(b'\xff')     # UnicodeDecodeError: invalid start byte
os.fsencode('\udcff')    # b'\xed\xb3\xbf',不是 b'\xff'

也就是说 PEP 383 的往返在 Windows 上不成立:surrogatepass 会把代理码位按 UTF-8 的 3 字节形式编码,而不是还原成原始单字节。如果你的代码靠 os.fsdecode 兜住非法文件名,在 Linux 上能过、在 Windows 上会抛错。同族的路径语义分歧我另写过一篇 Windows 路径的八处分歧,编码这一层是它的下游。

自定义 handler 的三个死法

codecs.register_error 的协议是「返回替换内容和新位置」,文档没有写「新位置必须前进」。我按文档写了个不前进的 handler,结果是死循环:5 秒超时、无异常、无输出、进程一直转。这不是文档遗漏,是它确实不检查——写 handler 时位置一定要手动推进。

另外两个是类型错误,都属于「跑起来才知道」:

所以一个 handler 要同时服务两个方向,第一行就得判 isinstance(err.object, bytes)。

strict 只保证「不合格就报错」,不保证「解对了」

这是全篇最值得记住的一条。strict 的语义是「编码规则不认就抛异常」,可很多编码几乎什么都认。取 10 个常用中文词,把它们 UTF-8 编码后的字节用 cp936(本机 locale.getencoding() 的值)按 strict 解:

50% 的静默错译率,而且不报错、不告警、长度还差不多。所以判断「解码对不对」不能靠有没有异常,只能靠往返比对或抽样人工核对。这类「看起来一样」的问题,我在 Unicode 规范化的七个坑 里也踩过一次。

决策表:按场景挑策略

场景建议理由
读别人的文件、要原样改回surrogateescape,读写成对唯一能逐字节往返
读日志、只要人能看懂replace保留「这里坏过」的痕迹,长度稳定
喂给 JSON 或 XML 或 CSV 解析先 surrogateescape 定位,再单独修数据replace 会让文件合法、字段残缺
编码导出给旧系统xmlcharrefreplace 或 namereplace显式可读,不静默丢字
二进制、图片、压缩包根本不要解码errors 不解决「本来就不是文本」

最后一行是前提:errors 只处理「是文本但字节不合法」,处理不了「这压根不是文本」。把 PNG 当 UTF-8 读,换成哪个 handler 都救不回来。

两个真实报错,以及定位顺序

报错一:UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe9 in position 3: invalid continuation byte

position 是解码缓冲区内的偏移,不是文件行号。我用 4 行的文件测试,第 3 行出错,报的却是 position 27——那是整份文件内的字节偏移,因为缓冲读取一次就把整块(这份 38 字节的文件是全部)解完了,跟你正在读第几行无关。定位顺序:先用 errors='surrogateescape' 把文件整段读进来,再逐行 encode('utf-8','surrogateescape') 找出第一个抛错的行——这样能直接拿到行号。

报错二:UnicodeEncodeError: 'utf-8' codec can't encode character '\udce9' ... surrogates not allowed

看到 U+DC80 到 U+DCFF 区间的字符,基本可以断定上游某处用了 errors='surrogateescape'(或它来自 os.fsdecode)。处理方式不是换成 errors='ignore' 蒙过去,而是回到上游,确认那个 handler 是否成对使用。

FAQ:四个常被问到的边界

Q:能不能干脆全局设成 errors='surrogateescape'?

A:读路径可以,写路径要成对,中间任何一次普通 encode(比如 json.dumps 之后 .encode('utf-8')、写数据库驱动、发 HTTP 请求)都会抛错。它适合「原样搬运」,不适合「参与计算」。

Q:replace 会不会破坏 JSON 结构?

A:不会。U+FFFD 是合法字符,json.loads 照常通过;被破坏的是字段内容。真正让 JSON 解析失败的是 backslashreplace,因为 \x 不是合法转义。

Q:为什么 ignore 之后长度看着没变多少?

A:一个 3 字节的汉字被整段丢掉只少 3 个字节;但如果一个字段整段是中文,ignore 会把它变成空字符串,而长度变化在总量里几乎看不出来。

Q:文档说文件系统用 surrogateescape,为什么我的 Windows 报错?

A:本机 sys.getfilesystemencodeerrors() 是 'surrogatepass'。判断这类问题不要背文档结论,直接打印两个值:sys.getfilesystemencoding() 和 sys.getfilesystemencodeerrors()。

结语

五个 handler 里,只有一个能完成往返,而且它要求你在读写两头都记得用同一个值。其余四个都有各自的合理场景——但都建立在「你知道自己在丢什么」的前提上。下次想把 errors 从 strict 改成 ignore 之前,先问一句:这个字节丢了,下游谁会以为它是完整的?

本文不含任何联盟推广链接。文中所有数字来自本机 CPython 3.13.14 加 Windows 11(10.0.26300)实测,编码语义以 docs.python.org 的 codecs 与 unicode HOWTO 两页为准。

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页