Python 读文件报 UnicodeDecodeError（utf-8/gbk codec can't decode byte）——文件编码与默认编码不匹配

你会遇到什么

open(path).read、pandas.read_csv(path)、configparser 等读文件时直接抛异常：Windows 中文环境报 'gbk' codec can't decode byte 0xad ...；Linux/mac 报 'utf-8' codec can't decode byte 0xd6 ...。

文件是别人发的/从旧系统拷来的/Excel 另存的。不是文件坏了，也不是代码逻辑错——是「文件编码」与「读取环境」不匹配。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

open 不指定 encoding 时用系统默认编码：

文件实际编码 ≠ 默认编码时，解码到第一个非 ASCII 字节就抛 UnicodeDecodeError。

open 不传 encoding 时用「系统默认编码」（locale 决定），而不是「文件实际编码」——Python 无法知道文件是什么编码，只能按默认假设解码。Windows 中文版默认 GBK（cp936）、Linux/mac 默认 UTF-8；文件编码与默认编码不一致时，解码到第一个非 ASCII 字节就抛 UnicodeDecodeError。

确定性推论：报错里的编码名就是当前环境的默认编码（gbk codec can't decode = 文件是 UTF-8、环境默认 GBK），不是文件「坏了」；解法是显式指定：读 UTF-8 文件写 open(f, encoding="utf-8")（或 utf-8-sig 兼容 BOM），读 GBK 旧文件写 encoding="gbk"；

脚本跨机器跑（Windows/Linux）必须显式 encoding，否则同一脚本两台机器行为不同；判断路径：file <文件> 看真实编码，再对照报错里的 codec 名。

一步步来

1. 先看文件真实编码 — 必做

file xxx.txt

输出 UTF-8 / ISO-8859（GBK）/ GB18030 等；或 xxd xxx.txt | head 看字节。

2. 读时显式指定 encoding（正解） — 必做

读 GBK 文件：

open(path, encoding='gbk')

GB18030 更全：encoding='gb18030' 兼容 GBK 且不丢生僻字。读 UTF-8 文件：open(path, encoding='utf-8')（在 Windows 上也稳）；pandas：pd.read_csv(path, encoding='gbk')。

3. 统一转码（治本，适合批量） — 必做

iconv -f gbk -t utf-8 old.txt > new.txt

或 Excel 里另存为 UTF-8；项目里约定所有文本文件统一 UTF-8。

4. 兜底容忍 — 必做

open(path, errors='replace') 或 errors='ignore' 不抛异常——但坏字节变 �，内容不可逆丢失，只适合日志/非关键解析。

5. stdout 也乱码时 — 必做

print 中文在 GBK locale 下输出乱码，加 PYTHONIOENCODING=utf-8（或 sys.stdout.reconfigure(encoding='utf-8')）——那是输出编码问题，与读取分开排查。

怎么确认修好了

显式编码读取正常（实测输出形态）：

encoding='gbk' 读 GBK 文件 → 正常输出「中文测试行」（exit 0，实测）
GBK locale 下 encoding='utf-8' 读 UTF-8 文件 → 正常（exit 0，实测）

复现基线：默认读 GBK 文件 → 'utf-8' codec can't decode byte 0xd6（exit 1，实测）。

其它环境的表现

症状

open(path).read、pandas.read_csv(path)、configparser 等读文件时直接抛异常：

UnicodeDecodeError: 'gbk' codec can't decode byte 0xad in position 2: illegal multibyte sequence
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd6 in position 0: invalid continuation byte

特征：Windows 中文环境（默认 GBK/cp936）读 UTF-8 文件报 'gbk' codec can't decode——最常见；Linux/mac（默认 UTF-8）读 GBK/旧文件报 'utf-8' codec can't decode；文件是别人发的/从旧系统拷来的/Excel 另存的（GBK 或 GB18030）；file xxx 显示 ISO-8859 之类（非 UTF-8）。

原因

open 不指定 encoding 时用系统默认编码：Windows 中文版是 GBK（cp936），Linux/mac 是 UTF-8。文件实际编码 ≠ 默认编码时，解码到第一个非 ASCII 字节就抛 UnicodeDecodeError。这是「文件编码」与「读取环境」不匹配，不是文件坏了，也不是代码逻辑错。

解法

1. 先看文件真实编码：file xxx.txt（输出 UTF-8 / ISO-8859（GBK）/ GB18030 等），或 xxd xxx.txt | head 看字节。
2. 读时显式指定 encoding（正解）：

• 读 GBK 文件：open(path, encoding='gbk')（GB18030 更全：encoding='gb18030' 兼容 GBK 且不丢生僻字）；
• 读 UTF-8 文件：open(path, encoding='utf-8')（在 Windows 上也稳）；
• pandas：pd.read_csv(path, encoding='gbk')。

1. 统一转码（治本，适合批量）：iconv -f gbk -t utf-8 old.txt > new.txt（或 Excel 里另存为 UTF-8）；项目里约定所有文本文件统一 UTF-8。
2. 兜底容忍：open(path, errors='replace') 或 errors='ignore' 不抛异常——但坏字节变 �，内容不可逆丢失，只适合日志/非关键解析。
3. stdout 也乱码时：print 中文在 GBK locale 下输出乱码，加 PYTHONIOENCODING=utf-8（或 sys.stdout.reconfigure(encoding='utf-8')）——那是输出编码问题，与读取分开排查。