Python 3.15 UTF-8 默认编码迁移时的兼容重点

Python 3.15.0 已于 2026 年 10 月 9 日发布稳定版，其中一项会直接影响跨平台项目的变化是：Python UTF-8 Mode 现在默认启用，未显式传入 encoding 的文本 I/O 默认使用 UTF-8，而不再随系统环境变化。这会让多数现代项目更一致，但依赖 Windows 本地代码页、旧式文本文件或外部工具默认编码的程序，需要在升级前明确文本边界。

官方网站：https://www.python.org/

迁移时最重要的不是把所有调用机械地改成 encoding="utf-8"，而是先回答“这批字节的协议编码是什么”。已知是 UTF-8 的文件应显式写 UTF-8；明确跟随操作系统本地编码的文件应使用 encoding="locale"；编码未知的外部输入，应在二进制边界完成识别或按业务协议处理。

变化的准确范围：默认值变了，显式值没有变

PEP 686 的核心是从 Python 3.15 起默认启用 UTF-8 模式。直接受影响的是没有指定编码的文本操作，例如 open(path)、Path.read_text()、TextIOWrapper，以及使用默认文本包装器的标准流和部分子进程管道。

以下几类行为要分开理解：

• 文本文件默认编码：未指定 encoding 时，Python 3.15 默认使用 UTF-8。
• 显式编码：encoding="gbk"、encoding="cp1252" 等行为不变。
• 明确使用 locale：encoding="locale" 会使用当前 locale 编码，不会被 UTF-8 默认值替代。
• 源码文件：Python 源码长期以来默认就是 UTF-8；本次迁移重点是运行期文本 I/O，不是重新定义源码编码。
• 回退开关：可用 PYTHONUTF8=0 或 -X utf8=0 临时恢复原有 locale 相关默认行为。

先建立迁移基线，不要凭感觉改代码

指标驱动的做法，是在修改前后记录同一组数字。这里不预设“应该有多少处问题”，而是要求项目给出自己的基线：

先在 Python 3.15 下开启可选的默认编码警告。命令块中的两个执行方式用途不同：第一个寻找隐式编码调用，第二个模拟关闭 UTF-8 模式后的兼容路径。

# 开启 EncodingWarning，完整运行测试套件并收集隐式编码调用点
python3.15 -X warn_default_encoding -m pytest -q

# 临时关闭 UTF-8 模式，比较旧式 locale 默认行为下的测试结果
python3.15 -X utf8=0 -m pytest -q

也可以在 CI 中设置 PYTHONWARNDEFAULTENCODING=1。警告只是定位工具，不代表每一处都必须改成 UTF-8；最终选择取决于数据协议。

按数据来源选择修复方式

已知是 UTF-8 的项目文件

JSON、TOML、Markdown、项目配置和现代服务导出的文本通常已有明确 UTF-8 约定。显式写出编码可以让 Python 3.10 至 3.15 以及不同操作系统保持一致。

from pathlib import Path

# 项目配置协议明确为 UTF-8，跨 Python 版本保持相同行为。
text = Path("settings.toml").read_text(encoding="utf-8")

# 输出文件同样明确 UTF-8，避免交给系统 locale 决定。
Path("report.txt").write_text(text, encoding="utf-8", newline="\n")

确实跟随系统本地编码的文件

某些 Windows 行业软件仍会按活动代码页生成文本。这种场景不应假装文件是 UTF-8，而应把依赖写清楚。Python 3.10 起可使用 encoding="locale" 明确表示“按当前系统 locale 解码”。

from pathlib import Path

# 该文件由本机旧式软件生成，协议就是当前系统本地编码。
legacy_text = Path("legacy-export.txt").read_text(
    encoding="locale",
    errors="strict",
)

# strict 会在字节不符合预期时立即失败，避免静默产生乱码。
print(legacy_text)

如果业务协议明确写的是 GBK、Shift_JIS 或 Windows-1252，优先直接写具体编码名，而不是 locale。这样即使任务迁移到另一台机器，解码规则也不会变化。

标准输入输出与子进程管道

Python UTF-8 模式还会影响标准输入、标准输出、标准错误和文本管道。最容易遗漏的是 subprocess.run(..., text=True)：当没有传入 encoding 时，它会使用文本包装器默认值。与自有工具通信时，应在两端约定 UTF-8；与 legacy 工具通信时，应使用对方协议要求的编码。

import subprocess

# 与自有命令行工具约定 UTF-8，避免父子进程依赖各自 locale。
result = subprocess.run(
    ["report-tool", "--format", "text"],
    capture_output=True,
    text=True,
    encoding="utf-8",
    errors="strict",
    check=True,
)

# stdout 已按约定解码，异常退出会由 check=True 明确报告。
print(result.stdout)

编码未知或混杂的外部输入

不要用 errors="ignore" 掩盖问题。对网络响应、上传文件或第三方批量数据，先保留为 bytes，依据协议头、文件规范或可靠元数据选择解码器。若数据源没有编码契约，应把“如何识别”作为业务规则，而不是依赖 Python 的默认值猜测。

最可能暴露问题的四类项目

1. Windows 桌面工具：读取由旧软件生成的 ANSI、GBK 或其他本地代码页文件。
2. 数据交换脚本：导入导出 CSV、日志和报表，却没有记录编码约定。
3. 子进程封装层：使用 text=True 与非 UTF-8 命令行工具交换内容。
4. 依赖默认编码的库：库函数内部调用 open()，调用方无法直接传入编码。

多数 Linux 服务原本就在 UTF-8 locale 下运行，升级后可能没有任何可见变化；风险更集中在 Windows 本地编码、历史数据和跨进程边界。没有报错不等于没有风险，因为某些单字节编码组合会产生乱码或静默数据变化，而不是立即抛出 UnicodeError。

回退开关只用于隔离问题

PYTHONUTF8=0 和 -X utf8=0 可以帮助确认故障是否由新默认值触发，也能给短期部署留出缓冲。但长期把开关固定为关闭状态，会继续保留跨平台差异。更可靠的迁移顺序是：

1. 开启 EncodingWarning，记录所有隐式文本边界；
2. 分别在 UTF-8 默认模式和关闭模式运行同一套测试；
3. 为 UTF-8、本地编码和外部协议逐一写出显式 encoding；
4. 补充 Windows 与类 Unix 环境的输入输出样本；
5. 移除回退开关，再比较警告数、异常数和快照差异。

迁移完成后的验收清单

• 项目自有文本格式均写明 UTF-8 或其他明确编码；
• 使用 locale 的位置都有真实的系统编码依赖理由；
• 子进程、管道、标准流和第三方工具交换均有编码契约；
• EncodingWarning 已归零，或每个保留项都有明确说明；
• 测试覆盖 Python 3.15 默认模式与必要的 legacy 样本；
• 回退开关不再是生产环境长期配置。

Python 3.15 的 UTF-8 默认值减少了“同一份代码在不同机器上使用不同默认编码”的不确定性，但不会替项目判断历史文件和外部协议。最有效的迁移不是全局替换，而是把每一个文本边界变成可解释、可测试、可度量的显式选择。

参考资料

• Python 3.15.0 官方发布页
• What’s New In Python 3.15
• PEP 686：Make UTF-8 mode default
• Python 命令行与环境变量文档