Python pathlib 怎样指定文本文件编码读取

同一份文本文件在开发机能正常读取，换到另一台机器却出现 UnicodeDecodeError，最常见的原因不是 pathlib 失效，而是读取时把“文件实际编码”和“运行环境默认编码”混在了一起。标题问题的直接答案是：文件编码已知时，把它明确写进 Path.read_text(encoding="...")；文件可能带少量坏字节时，再根据业务决定 errors 策略。

官方地址：https://docs.python.org/3/library/pathlib.html

推荐把编码当成输入协议的一部分。配置、CSV、日志和接口落盘文件如果约定为 UTF-8，就显式传入 encoding="utf-8"；不确定来源时不要直接用 errors="ignore" 把证据抹掉。

先判断：为什么省略 encoding 会埋下差异

Path.read_text() 的 encoding、errors 和 newline 参数与内置 open() 的文本读取参数含义一致。省略 encoding 并不是“自动识别文件编码”，而是交给当前 Python 文本 I/O 的默认策略。不同 Python 版本、UTF-8 模式和系统区域设置可能让默认结果不同，因此跨机器处理数据时最好把约定写出来。

要先分清两个问题：文件是二进制还是文本，以及文本采用什么字符集。read_text() 返回已经解码的 str；如果输入是压缩包、图片或协议帧，应改用 read_bytes()，不要为了得到字符串强行猜编码。

文件编码已知时，直接指定 encoding

例如团队约定所有配置文件使用 UTF-8，就让读取调用表达这个约定。参数名写全比依赖位置参数更容易审查，后续切换为 gb18030、utf-16 等来源格式时也不容易漏改。

from pathlib import Path

config_path = Path("settings.txt")

try:
    # 明确声明输入协议，避免依赖运行机器的默认编码。
    text = config_path.read_text(encoding="utf-8")
except FileNotFoundError:
    # 路径不存在是输入问题，交给调用方决定是否使用默认配置。
    raise RuntimeError(f"配置文件不存在：{config_path}")
except UnicodeDecodeError as exc:
    # 编码不匹配时保留原异常，便于定位文件来源或修正协议。
    raise RuntimeError(f"配置文件不是约定的 UTF-8：{config_path}") from exc

print(text)

这里的关键不是把所有异常都改写成一条提示，而是把“找不到文件”和“文件存在但不能按约定解码”分开。示例中的代码只展示处理边界，未把输出当成本文已经执行过的运行证据。

errors 决定坏字节是失败还是被替换

errors 只解决“解码遇到无法映射的字节时怎么办”，不能替代正确的 encoding。默认的 strict 会抛出异常，适合配置、代码、金额和标识等不能悄悄变化的内容；replace 会用替代字符保留大致文本形状，适合尽量展示日志；ignore 会跳过无法解码的部分，只有在丢字风险已经被业务明确接受时才考虑。

from pathlib import Path

log_path = Path("legacy.log")

# 展示型日志允许保留可读轮廓，但替换字符必须被下游识别。
preview = log_path.read_text(encoding="utf-8", errors="replace")

# 结构化配置不应静默丢字；默认 strict 会让错误尽早暴露。
strict_config = Path("app.conf").read_text(encoding="utf-8", errors="strict")

不要把 replace 的结果再当作原始事实写回数据库，也不要把 ignore 读取后的文本用于签名、主键或审计字段。若必须容错，至少记录文件来源、选择的编码和“发生过替换”的状态。

遇到 UnicodeDecodeError 时按证据排查

先确认文件来自哪里、生成程序声明了什么编码，再确认代码传入的 encoding 是否与协议一致。不要看到异常就轮流试一串编码并选“能读出来”的那个：某些错误编码虽然不抛异常，得到的中文也可能已经损坏。

1. 确认路径对应的确实是目标文本文件，不要把压缩或二进制文件交给 read_text()。
2. 查生成方或导出设置，优先拿到明确的编码约定。
3. 用严格解码保留错误位置；不要先用 ignore 清洗后再判断原文件。
4. 如果必须兼容历史文件，将“识别、转换、保存统一编码”作为独立步骤，并保留原始文件。

Python 3.15 文档已说明文本打开的默认编码变为 UTF-8；跨版本项目仍不应把默认值当作业务协议。显式传入编码既能表达意图，也能减少升级、容器镜像和开发机区域设置变化带来的差异。

发布前可以复用的读取检查清单

• 这是文本输入吗？如果不是，改用 read_bytes()。
• 文件编码有可靠来源吗？有就显式传入 encoding。
• 内容损坏时必须失败，还是允许展示近似文本？据此选择 strict 或 replace。
• 是否会把容错后的文本用于金额、签名、主键或审计？如果会，禁止静默丢字。
• 是否需要保留换行形式？需要时再单独评估 newline，不要把它和编码问题混为一谈。

归纳起来，Path.read_text(encoding="utf-8") 是已知文本协议下最清晰的默认写法；errors 是异常处理策略，不是编码探测器。把二者与文件来源一起记录，排查乱码时就能从“猜”回到可解释的输入约定。

两个容易混淆的问题

指定了 UTF-8 仍然报错怎么办？ 先相信异常提供的证据，回到文件生成方确认编码；不要只把 errors 改成 ignore。如果文件确实是其他编码，应修改 encoding，而不是掩盖不匹配。

read_text 需要手动 close 吗？ 不需要。官方文档说明该方法会打开并关闭文件；如果需要逐行读取超大文件或控制更多 I/O 参数，再使用 Path.open() 配合 with。