pathlib 编码怎么配置或排查

我第一次遇到这个问题，是把同一份配置文件放到 Windows 和 Linux 两台机器上处理：代码用 Path.read_text()，一台机器正常，另一台却出现乱码或 UnicodeDecodeError。真正该改的通常不是系统语言，而是把文件的字节编码写进读取和写回代码里。UTF-8 文本就显式传入 encoding='utf-8'；历史中文文件则先确认导出工具，再选择 cp936、gb18030 或其他实际编码。

官方文档：https://docs.python.org/3/library/pathlib.html

pathlib 只能负责打开路径和传递文本 I/O 参数，不能替你猜出文件原本采用的编码。排查时保留原始字节，先确认 BOM 或来源约定，再用显式 encoding 解码；不要用 errors='ignore' 把坏数据静默删掉。

先把编码问题分成读取、写入和换行

文件编码问题常被混成“中文显示不对”，但现场至少有三条线：打开时把 bytes 解码成 str，保存时把 str 编回 bytes，以及不同系统对换行符的处理。先判断异常发生在哪一层，后面的修复才不会跑偏。

这里有个容易忽略的边界：编码决定一个字节序列如何变成字符，换行决定文本中的行结束如何被读取或写出。它们相关，但不是同一个开关。

给 pathlib 明确 encoding，别依赖系统默认值

只要文件格式是你能约定的，就不要省略编码。默认值可能来自当前平台的区域编码，同一段代码换到另一台机器后就可能表现不同。对新建的 JSON、CSV、Markdown 或配置文件，我一般把 UTF-8 写在代码里，让输入输出契约可读、可 review。

from pathlib import Path

# 输入格式由业务约定为 UTF-8；strict 让坏字节尽早暴露
source = Path('data/report.txt')
text = source.read_text(encoding='utf-8', errors='strict')

# 只有确认文件来自旧版中文 Windows 工具时，才按来源选择编码
legacy = Path('data/legacy-report.txt')
legacy_text = legacy.read_text(encoding='gb18030', errors='strict')

errors='strict' 是安全的排查起点：它会让不匹配立即失败。errors='replace' 会插入替换字符，适合只看大致结构的临时预览；进入清洗、计费、导入或审计流程前，不能把它当修复。errors='ignore' 可能直接丢字节，除非数据损失已经被明确接受，否则不要使用。

如果文件确实是带 UTF-8 BOM 的文本，可以用 encoding='utf-8-sig' 读取，让 BOM 不出现在首个字符里；写回时是否保留 BOM，要按下游程序的兼容要求决定。

遇到乱码时先检查 BOM 和原始字节

不知道编码时，不要把“能成功 decode”当成“编码判断正确”。许多单字节编码对任意字节都能给出字符，结果看似没有异常，实际内容已经错了。先读 bytes，查看 BOM、文件来源和失败位置，再用几个有依据的候选编码做小范围对比。

from pathlib import Path

raw = Path('data/input.txt').read_bytes()

# BOM 只能提供线索，最终仍要结合导出工具的格式约定
if raw.startswith(b'\xef\xbb\xbf'):
    encoding = 'utf-8-sig'
elif raw.startswith(b'\xff\xfe'):
    encoding = 'utf-16'
else:
    encoding = 'utf-8'

try:
    text = raw.decode(encoding, errors='strict')
except UnicodeDecodeError as exc:
    # 保留位置，便于回到原始字节核对，而不是吞掉异常
    raise ValueError(f'文件可能不是 {encoding}，坏字节位置为 {exc.start}') from exc

如果没有 BOM，优先问清楚文件由谁生成、导出时选了什么格式，并把这个结论记录到接口或任务配置中。调试时可以打印 raw[:32].hex() 看开头字节，但不要把整个敏感文件内容写进日志。

写回文件时保持同一套编码契约

读取成功不等于写回安全。比如输入用 gb18030，中间得到的是 Python 字符串，最后却无意间按系统默认编码写出，下一次读取仍会失败。把编码和换行一起放到写入点，必要时先输出到新文件，确认无误后再替换原文件。

from pathlib import Path

target = Path('data/report-clean.txt')

# 这里与读取约定一致；newline 只控制换行，不改变字符编码
with target.open('w', encoding='utf-8', errors='strict', newline='\n') as file:
    file.write(text)

# 小样本 round-trip 只检查编码契约，不代表业务内容已经正确
round_trip = target.read_text(encoding='utf-8', errors='strict')
if round_trip != text:
    raise RuntimeError('写回后的文本与内存文本不一致')

生产流程里可以把 encoding 作为配置字段或函数参数，并在文件名、接口说明或任务元数据中记录来源格式。不要用修改 PYTHONUTF8 或系统区域设置来掩盖某个文件的真实格式；启动级别的 UTF-8 模式影响默认行为，却不会把已经是 GBK 的文件 magically 变成 UTF-8。

常见问题

pathlib 的 read_text 为什么在不同电脑上结果不同？

因为省略 encoding 时，底层文本打开逻辑可能使用平台相关的默认编码。跨平台输入应显式指定编码。

没有 BOM，能不能自动判断编码？

不能仅凭 pathlib 可靠判断。应结合文件生成方的约定、格式文档和原始字节做验证；候选编码解码成功不代表语义正确。

errors='replace' 适合正式导入吗？

通常不适合。它能帮助你查看剩余结构，但替换字符意味着原始信息可能已丢失。正式导入应使用真实编码和 strict，发现异常就让任务失败并修复来源。

编码正确但换行符不一致怎么办？

把编码和换行分开处理，在 Path.open() 中显式设置 newline，再检查版本和下游工具的换行约定。