一、基础知识

文件编码问题的根源,其实只有一句话:文件在磁盘上存的是字节,而程序里操作的是字符,两者之间需要"翻译",翻译规则就是编码。

  • 字符:人眼看到的文字,比如"中"这个字,是一个抽象符号。
  • 字节:计算机实际存储的数字序列。
  • 编码:把字符转成字节(编码)、把字节转回字符(解码)的规则表。

UTF-8 是目前最主流的编码,它用 1 到 4 个字节表示一个字符,兼容英文 ASCII,能表示全世界几乎所有文字。读写中文文本,优先统一用 UTF-8,这是最省心的选择。

BOM(字节顺序标记) 是放在文件最开头的一小段特殊字节,用来声明"这个文件是什么编码"。在 UTF-8 里,BOM 是可选的;Windows 的一些工具(如旧版记事本、Excel)喜欢在保存 UTF-8 文件时加上 BOM,于是有了一种常被称作 "UTF-8 with BOM" 的格式。问题是:很多程序不认识这个 BOM,会把它当成正文的一部分,导致文件开头出现一个看不见的特殊字符——这就是大量诡异 bug 的来源。

Python 的 open() 函数通过 encoding 参数指定编码。永远显式写出 encoding,不要依赖系统默认值:不同操作系统、不同环境的默认编码可能不同(Windows 上常是本地代码页,Linux 上常是 UTF-8),这正是"我的电脑上正常、别人电脑就乱码"的元凶。部分较新的 Python 版本或开启了 UTF-8 模式(如 PYTHONUTF8=1)的环境,默认编码已经是 UTF-8,但仍不应依赖这个默认值。处理带 BOM 的 UTF-8 时,编码名称要写 utf-8-sig,它会自动去掉开头的 BOM;写文件时用它则会加上 BOM。

二、实操步骤

第 1 步:查看当前环境的默认编码

import locale
print("首选编码:", locale.getpreferredencoding())   # 3.11+ 可用 locale.getencoding()

open() 不写 encoding 时,用的是 locale.getpreferredencoding()(3.11+ 可用 locale.getencoding())返回的区域首选编码。注意两个容易混淆的函数:sys.getdefaultencoding() 恒为 utf-8,与 open() 的默认编码无关;sys.getfilesystemencoding() 只决定文件路径的编码,也不管文本内容。了解这一点,才能正确判断"没写 encoding 时会用哪种"。

第 2 步:以 UTF-8 正确写入和读取

text = "你好,世界n第二行"

with open("demo.txt", "w", encoding="utf-8") as f:
    f.write(text)

with open("demo.txt", "r", encoding="utf-8") as f:
    content = f.read()
print(content)

关键就是每次都写 encoding="utf-8"。

第 3 步:观察不做声明时的乱码

# 故意用错误编码去读 UTF-8 文件
with open("demo.txt", "r", encoding="gbk") as f:
    try:
        print(f.read())
    except UnicodeDecodeError as e:
        print("解码失败:", e)

用错编码轻则乱码、重则直接抛 UnicodeDecodeError。

第 4 步:处理带 BOM 的文件

# 写一个带 BOM 的 UTF-8 文件
with open("bom.txt", "w", encoding="utf-8-sig") as f:
    f.write("带 BOM 的内容")

# 用 utf-8-sig 读取,BOM 会被自动去掉
with open("bom.txt", "r", encoding="utf-8-sig") as f:
    print(repr(f.read()))

对比一下:若用普通 utf-8 读取带 BOM 的文件,开头会多出一个 ufeff 字符:

with open("bom.txt", "r", encoding="utf-8") as f:
    print(repr(f.read()))     # 开头出现 'ufeff'

第 5 步:不知道编码时,先看原始字节

with open("unknown.txt", "rb") as f:      # rb = 二进制模式,不做解码
    raw = f.read(32)                       # 只看前 32 个字节
print(raw)

根据字节特征做初步判断:UTF-8 中文多为 e4~e9 开头的三字节序列;GBK 中文多为两字节序列。也可以使用 chardet 等第三方库辅助检测(安装与用法以官方文档为准),但检测结果仅供参考,最终要靠能否正确解码来验证。

第 6 步:批量转换文件编码(UTF-8 with BOM → UTF-8)

from pathlib import Path

for path in Path(".").glob("*.txt"):
    data = path.read_bytes()
    if data.startswith(b"xefxbbxbf"):          # 检测 UTF-8 BOM 的三字节头
        path.write_bytes(data[3:])                  # 去掉 BOM 后写回
        print("已去除 BOM:", path)

这段代码先以字节方式读取,检测开头三字节 EF BB BF(即 UTF-8 的 BOM),存在就切掉前 3 字节再写回,整个过程不涉及解码,安全可控。

三、关键细节

  • 读写都要写 encoding:只读或只写其中一边声明,另一边用默认编码,同样会出问题,两边要成对统一。
  • utf-8 与 utf-8-sig 要匹配文件实际格式:确认文件是否带 BOM,再选对应编码,搞反了就会出现开头的 ufeff 或解码错误。
  • 二进制模式配合 bytes:用 rb / wb 打开时,读写的是 bytes,不能写入 str,需要先 .encode("utf-8")。
  • errors 参数要慎用:errors="ignore" 会直接丢弃无法解码的字节,errors="replace" 会用替代符顶替,二者都会造成数据损失,只在明确接受损失时使用。
  • 换行符差异:Windows 用 rn,Linux/macOS 用 n,Python 的文本模式默认会做转换;处理跨平台文件时要留意 newline 参数。
  • "看起来正常"不代表编码正确:终端能显示中文,只说明终端与文件编码碰巧一致,换个环境可能就乱,务必显式声明。

四、常见错误

现象 原因 修正
读出来全是乱码 读取编码与文件实际编码不一致 先用字节查看确认编码,再用正确的 encoding 读取
UnicodeDecodeError 用错编码,字节序列无法解码 核对文件真实编码,或尝试 utf-8-sig、gbk 等
文本开头多出 ufeff 用 utf-8 读了带 BOM 的文件 改用 encoding="utf-8-sig" 读取
写入后别人打开乱码 写文件没声明编码,用了本机默认值 写入时显式 encoding="utf-8"
JSON 解析报开头有非法字符 JSON 文件带 BOM,解析器不接受 读取时用 utf-8-sig,或先去除 BOM
二进制模式写入报类型错 向 wb 打开的文件写入了 str 先用 .encode("utf-8") 转成 bytes

五、排查方法

拿到一个"乱码文件",按这个顺序照做:

  1. 确认模式:看代码是文本模式还是二进制模式,乱码排查阶段建议先用 rb 看原始字节。
  2. 查看头部字节:raw[:32],若开头是 EF BB BF 则是带 BOM 的 UTF-8。
  3. 判断编码类型:三字节 e4~e9 序列多为 UTF-8 中文,两字节序列多为 GBK 类编码。
  4. 小样验证:取一小段字节,分别用 utf-8、utf-8-sig、gbk 尝试 .decode(),看哪个不报错且结果可读。
  5. 借助工具:必要时用 chardet 等库做辅助检测,但把结果当"候选",不要盲信。
  6. 统一读写编码:确定正确编码后,把读写两端的 encoding 都改成它,重跑验证。
  7. 批量修复:若是大量文件带 BOM,用第 6 步的字节级脚本统一去除,再逐个抽查。
  8. 验证结果:打印 repr(内容) 检查是否还有 ufeff 或乱码字符,确认无残留后再交付。

六、注意事项

  • 本文以 Python 3 的文本模式与 open() 行为为准,不同版本在默认编码、错误提示上可能略有差异,细节以对应版本官方文档为准。
  • 不要迷信"万能转码"工具:encode/decode 必须配对,先用错误编码解码再编码只会固化乱码,无法真正恢复原始数据。
  • chardet 等检测库不保证准确:短文本尤其容易误判,最终结果要以人工可读性和解码是否成功为准。
  • 处理重要数据前先备份:批量转码、去 BOM 会写回文件,操作前务必保留原始副本,避免不可逆损失。
  • 安全提示:处理来源不明的文本文件时,避免直接 eval/exec 其内容;对超大文件应采用分块读取,防止内存被撑爆。

免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。