中文乱码三件套:GBK 终端、UTF-8 文件、BOM 头各坑一次

同一份中文在 GBK 控制台、UTF-8 文件与带 BOM 的 JSON 之间转换会踩的五个坑,每个都有本机实测字节输出,末尾给出编码策略与排查顺序。

目录
  1. 一、坑 1:默认编码是 cp936,不是 UTF-8
  2. 二、坑 2:同一个中文,三种落盘字节
  3. 三、坑 3:BOM 让 json.loads 直接崩
  4. 四、坑 4:PowerShell 重定向的 UTF-16LE
  5. 五、坑 5:乱码排查的顺序错了,成本翻十倍
  6. 六、统一策略:四条就够了
  7. 结论
  8. 下一步

中文乱码之所以难查,是因为它经常不影响程序运行。脚本 exit 0、文件也生成了,只是内容变成 锟斤拷。等你在下游发现时,原始上下文早没了。

下面五个坑全部在 Python 3.14.8 + Windows 上实测,字节输出是复制出来的原文。

一、坑 1:默认编码是 cp936,不是 UTF-8

先看事实:

python
import locale, sys
print(locale.getpreferredencoding(False))  # cp936
print(sys.stdout.encoding)                 # gbk
print(sys.getfilesystemencoding())         # utf-8

三个值不一样。文件系统是 UTF-8,控制台是 GBK,而 locale 默认编码又是 cp936。 这意味着:

  • open(path) 不带 encoding → 用 cp936 读,遇到 UTF-8 中文就炸
  • print() 输出中文 → 编码成 GBK 字节,重定向到文件后再按 UTF-8 读就是乱码

验证后者:

bash
python exp_stdout.py > cn_gbk.txt 2>&1
xxd cn_gbk.txt | head -3
text
00000000: 7374 646f 7574 2e65 6e63 6f64 696e 6720  stdout.encoding
00000010: 3d20 6762 6b0d 0a43 4e20 3d20 bfc6 bcbc  = gbk..CN = ....
00000020: b0e5 bfe9 0d0a                           ......

bfc6 bcbc b0e5 bfe9 就是 GBK 的"科技板块"。文件本身没错,错的是写的人用 GBK,读的人以为 UTF-8。

修复有两档:

bash
# 临时:单次运行强制 UTF-8(stdout/文件默认都变 UTF-8)
python -X utf8 exp_stdout.py > cn_utf8.txt 2>&1
# 00000010: 3d20 7574 662d 380d 0a43 4e20 3d20 e7a7  = utf-8..CN = ..

# 或者用环境变量(对子进程同样生效)
PYTHONIOENCODING=utf-8 python exp_stdout.py > cn_io.txt 2>&1

e7a7 91e6 8a80 e69d bfe5 9d97 = UTF-8 的"科技板块",正确。

这里有个容易被忽略的细节:修复只解决了"输出",没解决"输入"。-X utf8 让 open() 的默认编码也变成 UTF-8,所以如果你读的文件其实是 GBK,加上这个参数反而会让原本"能读"的脚本崩掉。所以正确的顺序是先确定文件是什么编码,再决定要不要开 utf8 模式。

二、坑 2:同一个中文,三种落盘字节

我把同一句话用三种编码写三份,然后交叉解码:

python
cn = "科技板块恐慌指数"
Path("a_utf8.txt").write_text(cn, encoding="utf-8")
Path("b_utf8sig.txt").write_text(cn, encoding="utf-8-sig")
Path("c_gbk.txt").write_text(cn, encoding="gbk")

交叉解码结果(关键部分):

文件字节数头部按 utf-8按 utf-8-sig按 gbk
a_utf8.txt24e7a791OKOK假 OK(乱码)
b_utf8sig.txt27efbbbfe7多出 \ufeffOK失败
c_gbk.txt16bfc6bc失败失败OK

三个结论,每个都反直觉:

第一,UTF-8 文件用 GBK 解会"成功"并返回乱码。 因为 GBK 的双字节范围宽,大部分 UTF-8 字节序列都能凑成合法 GBK 字符。这是乱码最常见的成因:不报错,只是内容错。

第二,有 BOM 的文件用 utf-8 解会多一个 \ufeff 在开头。 字符串看起来正常,但 len() 多 1,== "科技板块恐慌指数" 返回 False。这种 bug 极难查——尤其是当你在做字符串相等判断、字典 key 匹配、正则 ^\d{4} 这类锚定匹配时,\ufeff 会让一切静默失配。

第三,BOM 用 GBK 解直接失败。 至少这次它报错了。

顺带一个推论:"解码成功"不等于"解码正确"。只有在你同时知道字节来源和期望内容时,解码结果才有意义。所以工程上更可靠的做法是:写文件时显式指定编码,读文件时也显式指定,两头对齐。

三、坑 3:BOM 让 json.loads 直接崩

这是 BOM 最典型的杀伤点。写一个带 BOM 的 JSON:

python
Path("brk.json").write_text(json.dumps({"a": 1}), encoding="utf-8-sig")
raw = Path("brk.json").read_bytes()
print(raw[:3].hex())   # efbbbf
json.loads(raw.decode("utf-8"))
text
JSONDecodeError: Unexpected UTF-8 BOM (decode using utf-8-sig): line 1 column 1 (char 0)

而这个报错还算友好的——它直接告诉你怎么修。换成 yaml、csv、configparser 就不一定这么明确了。csv 的典型表现是第一列表头变成 \ufeffid,然后你按 row["id"] 取值永远拿到空。

修法只有一条:读的时候用 utf-8-sig,它同时兼容带 BOM 和不带 BOM:

python
json.loads(raw.decode("utf-8-sig"))   # {'a': 1}

我当时以为:BOM 是 Windows 记事本的坏习惯,删掉就好。 实际是:BOM 有时是有意设计——为了让 Excel 双击打开中文 CSV 不乱码。我在一个数据项目里查到 32 个文件带 BOM,全部是写入方显式用 encoding="utf-8-sig" 造成的,属于正确设计,不该"修"。

这条教训很值:看到"不规范"的东西,先弄清它为什么存在,再决定改不改。

四、坑 4:PowerShell 重定向的 UTF-16LE

在 PowerShell 里用 > 捕获输出,文件是 UTF-16LE:

text
_probe_live/probe_live.out.txt   3,990 字节   首字节 0xff 0xfe  → UTF-16LE

这个文件用 cat 看会显示成一堆 < 和 >(因为每两个字节里有一个是 0x00),用 Python 按 UTF-8 读直接报错。

正确写法:

powershell
python script.py | Out-File -Encoding utf8 out.txt

在 Git Bash 里就简单了,> 是纯字节重定向,不掺编码——但要注意前面坑 1 说的:Python 自己会用 GBK 编码 stdout。两个"默认"叠在一起,就是你看到的乱码。

五、坑 5:乱码排查的顺序错了,成本翻十倍

这一点是流程问题,不是技术问题,但它是前面四个坑反复咬我的根本原因。

我在这上面花的最不值的一次,是一个"日报推送消息变乱码"的问题。当时的排查顺序是:

  1. 先怀疑网络传输 → 查了一遍,没问题
  2. 再怀疑推送渠道 → 换了个渠道,还是乱码
  3. 最后才去看文件字节 → 发现是 GBK

如果第一步就 xxd 一下,五分钟能定位。教训是:乱码排查永远从字节开始,从上游往下游走,不要从传输层往回猜。

正确的排查顺序:

步骤动作判断
1xxd file | head -3看头部字节定性
2按判断的编码试解解出来是否可读
3解不出来就试相邻编码UTF-8 ↔ GBK 是最常见的一对
4都失败才看传输/存储环节这时才是链路问题

六、统一策略:四条就够了

踩完这几个坑后我定了四条规则,之后再没被乱码咬过:

规则做法
1. 写文件永远显式指定编码open(p, "w", encoding="utf-8"),绝不省略
2. 读外部文件用 utf-8-sig兼容带/不带 BOM,零成本
3. 控制台输出加 -X utf8python -X utf8 或 PYTHONIOENCODING=utf-8
4. 需要 Excel 打开的中文 CSV显式写 utf-8-sig,然后别去"修"它

再补一条排查技巧:遇到乱码先看字节,不要看显示。

bash
xxd file.txt | head -3        # 或 od -An -tx1

看头部三个字节就能定性:

text
ef bb bf  → UTF-8 with BOM
ff fe     → UTF-16LE
e7 a7 91  → UTF-8 中文("科")
bf c6     → GBK 中文("科")

顺带一个自查命令,用来找出项目里所有潜在乱码源:

bash
# 所有 open() 但不带 encoding 的位置
grep -rn 'open(' --include=*.py . | grep -v 'encoding' | head -20

结论

三句话:

  1. 乱码几乎不报错。 所以必须靠"看字节"而不是"看显示"。
  2. BOM 不一定是缺陷。 先弄清它为什么在那里。
  3. 编码要两头对齐。 写的时候显式指定,读的时候也用同一个。

下一步

建议你现在就检查自己的项目:找出所有 open( 但不带 encoding= 的位置。这些是潜在的乱码源,改起来是机械劳动,收益是彻底的。改完再跑一次 xxd 抽查两个字,确认落盘字节跟你以为的一致。