📑 本页目录(点开跳转)
10 · 编码、路径和文件
实验记录怎么读
本页原有耗时、内存、报错和环境值保留为原文记录;本轮内容审校未逐项复跑这些实验。版本、硬件、数据和测量方法都会影响结果,示例中的倍数也不是保证。需要复现时先核对依赖版本,再在同一输入下比较。
⏱ 40 分钟 | ⭐ 「在我机器上好好的」十次里有八次是这一章的内容
🎯 一句话
open() 的默认文本编码取决于 Python 版本、UTF-8 模式和系统区域设置;不能仅凭 Windows、Linux 或 macOS 判断。读写已知格式时,显式使用该格式约定的编码;下文 cp936 是原文环境的一次记录。
换了机器、终端、工作目录或解释器版本,都可能改变原先没注意到的默认值。这一章分别核对文件内容、输出流和路径。
🧩 一、open() 的默认编码是个陷阱
先看原记录中的三个值。它们来自 Windows 11 上一次 Python 3.13 运行。
import locale, sys
print(locale.getpreferredencoding(False)) # cp936 ⭐ 就是 GBK
print(sys.getdefaultencoding()) # utf-8 ⚠️ 这个管的不是文件
print(sys.stdout.encoding) # utf-8
原环境里的默认文件编码是 cp936,与那次的 locale.getpreferredencoding(False) 相同。sys.getdefaultencoding() 是字符串编码 API 的默认值,例如 str.encode()。sys.stdout.encoding 则描述 print() 使用的输出流。要核对某个文件实际选了哪种编码,直接查看文本文件对象的 f.encoding。
下面保留原例。它写入 UTF-8,然后用环境默认编码读取。原环境按 cp936 解码,这组字节会触发错误。
import tempfile, os
d = tempfile.mkdtemp()
p = os.path.join(d, "zh.txt")
with open(p, "w", encoding="utf-8") as f: # 写的时候好好的
f.write("你好,世界")
with open(p) as f: # ⚠️ 读的时候没写 encoding
print(f.read())
# UnicodeDecodeError: 'gbk' codec can't decode byte 0x8c in position 14:
# incomplete multibyte sequence
原报错中的 'gbk' codec 指本次读取选用的解码器。写入时明确用的是 UTF-8,读写的编码在这个环境下没对齐。
读写文本前先确认格式:本站 UTF-8 源文件使用
encoding="utf-8";带 BOM 的 UTF-8 可用utf-8-sig;GBK 等旧文件必须按其实际编码读取。显式指定正确编码,比把所有文件都当 UTF-8 更可靠。
默认编码变了,磁盘里的字节还是原样
Python 3.15 默认开启 UTF-8 模式。用文本模式打开文件且省略 encoding 时,开启模式会选 UTF-8。启动时可用 -X utf8=0 或 PYTHONUTF8=0 关闭,关闭后使用区域编码。Python 3.7 至 3.14 也可能已开启 UTF-8 模式,例如启动时传 -X utf8 或设 PYTHONUTF8=1。排查时可以看 sys.flags.utf8_mode 和实际文件对象的 f.encoding。PEP 686 · Python 3.15 新功能
显式 encoding="gbk" 等编码名称会覆盖默认值。Python 3.11 起,encoding="locale" 明确选择区域编码,即使 UTF-8 模式已开启。以 "rb" 打开文件直接读 bytes,没有文本解码这一步。标准输出是单独配置的流,用 sys.stdout.encoding 查看。Python 文档 · open · Python 文档 · 标准流
假设旧系统明确用 GBK 导出「中文」,文件内容是十六进制的 D6 D0 CE C4。下面在临时目录中写入这四个原始字节,再换两种编码读取同一份文件。
from pathlib import Path
from tempfile import TemporaryDirectory
with TemporaryDirectory() as folder:
path = Path(folder) / "legacy.txt"
with open(path, "wb") as file:
file.write(bytes.fromhex("D6 D0 CE C4"))
with open(path, "rb") as file:
print("bytes:", file.read().hex(" "))
try:
with open(path, encoding="utf-8") as file:
file.read()
except UnicodeDecodeError as error:
print("UnicodeDecodeError:", error.encoding)
with open(path, encoding="gbk") as file:
text = file.read()
assert text == "中文"
print("GBK:", ascii(text))
程序依次打印 bytes: d6 d0 ce c4、UnicodeDecodeError: utf-8 和 GBK: '\u4e2d\u6587'。末行是 ascii() 用转义显示「中文」,便于在不同输出流中比较结果。这个实验的文件编码来自写入约定。实际排查时,报错中的 utf-8 只说明程序试了哪种解码,不能据此判定文件原来就是 GBK。
🧩 二、BOM:多出来的那个看不见的字符
有些工具(Excel 导出的 CSV 是重灾区)会在文件开头塞三个字节 EF BB BF,叫 BOM。
import tempfile, os
d = tempfile.mkdtemp()
p = os.path.join(d, "bom.txt")
with open(p, "w", encoding="utf-8-sig") as f: # 写入带 BOM
f.write("id,name")
a = open(p, encoding="utf-8").read()
b = open(p, encoding="utf-8-sig").read()
print(repr(a)) # '\ufeffid,name' ⚠️ 多了一个字符
print(repr(b)) # 'id,name'
print(a == b) # False
💀 它的杀伤力在于「看起来完全正常」:你 print(a) 出来就是 id,name,
但 a.split(",")[0] == "id" 是 False —— 真实的第一列名叫 '\ufeffid'。
于是典型症状是:df["id"] 报 KeyError,而你把列名打印出来看着一模一样。
⭐ 解法:读可能带 BOM 的文件用 encoding="utf-8-sig"(没有 BOM 时它行为和 utf-8 一样,
所以可以无脑用);写给 Excel 看的 CSV 主动用 utf-8-sig,否则 Excel 打开中文是乱码。
🧩 三、💀 print 一个 emoji 就能崩掉整个构建
⚠️ 这一节是本项目自己的事故,写在这里是因为它太典型了。
若当前标准输出流的编码不能表示 emoji,例如原文环境的 GBK,则:
print("✅ 全部链接有效")
# UnicodeEncodeError: 'gbk' codec can't encode character '\u2705' ...
💀 本项目的真实事故:构建脚本的最后一步是往页面里注入 SVG 图。
它跑在「旧图已被清掉、新图还没注进去」的中间态上。
那一步因为打印一个 ✅ 崩了,而外层 except 打印的是
「图例注入失败(不影响其他内容)」—— 在站点已经坏掉的时候报了平安。
全站 156 张图当场只剩 75 张。
⚠️ 更阴的一次:一个校验脚本检查全部通过之后,崩在打印 ✅ 全部链接有效 这一行上。
而它的失败信息里也有 emoji —— 所以「真有坏链」时同样崩。
你看到一个 traceback,却分不清是脚本坏了还是站点坏了。
先查看报错进程的 sys.stdout.encoding。如果脚本和接收方都约定 UTF-8,原示例可以用于有 buffer 的标准输出流。替换前先核对流的类型,例如部分 Notebook 或捕获工具提供的流没有这个属性。
import io, sys
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
errors="replace" 允许用替代标记输出无法编码的字符,会损失原始信息。它只影响这里的输出流,文件读取的编码仍由文件格式与 open() 的参数决定。
🧩 四、换行符:CSV 的双回车
Windows 的行尾是 \r\n,Unix 是 \n。Python 的文本模式会替你转换 —— 而这正是问题所在。
import tempfile, os, csv
d = tempfile.mkdtemp()
for nl in ("", None):
p = os.path.join(d, f"c{nl!r}.csv")
with open(p, "w", newline=nl, encoding="utf-8") as f:
csv.writer(f).writerow(["a", "b"])
print(f"newline={nl!r:6} → {open(p, 'rb').read()!r}")
# newline='' → b'a,b\r\n'
# newline=None → b'a,b\r\r\n' ⚠️ 两个 \r
⭐ csv 模块自己会写 \r\n,而 newline=None(默认)又把那个 \n 翻译成 \r\n ——
于是变成 \r\r\n。用 Excel 打开会看到每行之间多一个空行。
⭐ 规矩:
csv读写一律加newline=""。 这个参数的意思是「别动换行符,我自己管」,不是「用空字符串当换行符」。
🧩 五、pathlib:别再用字符串拼路径
import pathlib
p = pathlib.Path("/data") / "raw" / "x.csv" # ⭐ / 是重载过的
print(p) # 平台自适应的分隔符
q = pathlib.Path("a/b/c.tar.gz")
print(q.name) # c.tar.gz
print(q.stem) # c.tar ⚠️ 只脱一层
print(q.suffix) # .gz ⚠️ 只取最后一个
print(q.suffixes) # ['.tar', '.gz']
⚠️ .stem / .suffix 只处理最后一个点。c.tar.gz 的 stem 是 c.tar 不是 c。
要脱干净得自己循环,或者用 q.name.split(".")[0]。
常用的一把抓:
| 想干什么 | 写法 |
|---|---|
| 建目录(含父级、已存在不报错) | p.mkdir(parents=True, exist_ok=True) |
| 读写文本 | p.read_text(encoding="utf-8") · p.write_text(s, encoding="utf-8") |
| 读写二进制 | p.read_bytes() · p.write_bytes(b) |
| 遍历 | p.glob("*.csv") · p.rglob("*.csv")(递归) |
| 判断 | p.exists() · p.is_file() · p.is_dir() |
| 换后缀 / 换文件名 | p.with_suffix(".parquet") · p.with_name("new.csv") |
⚠️ 注意 read_text / write_text 也要写 encoding=,它们和 open() 一样默认跟平台。
可选深入:路径指向谁,写成功又能保证到哪一步?
链接语义与持久化要分别检查
硬链接是同一文件对象的另一个目录项;删除一个名字后,只要别的硬链接仍存在,文件内容仍可通过它访问。它通常不能跨文件系统,因为目录项中的对象标识只在所属文件系统内有意义,也通常不允许对目录这样操作。符号链接则存储目标路径,能跨文件系统,也可能指向不存在的目标;相对目标路径按链接所在目录解释,删掉目标就可能变成悬空链接。它们都不是复制文件。
下面只在临时目录里验证文件名与内容关系。Windows 的符号链接可能需要开发者模式/权限,文件系统也可能不支持;因此区分“确实验证”与“受限跳过”,不把跳过当通过。
from pathlib import Path
from tempfile import TemporaryDirectory
with TemporaryDirectory(prefix="g02-links-") as tmp:
root = Path(tmp)
original, hard, soft = (root / x for x in ("a.txt", "hard.txt", "soft.txt"))
original.write_text("hello", encoding="utf-8")
hard.hardlink_to(original) # new name -> same file, within this filesystem
assert original.samefile(hard)
symlink_ok = False
try:
soft.symlink_to(original.name)
symlink_ok = True
assert soft.read_text(encoding="utf-8") == "hello"
except (OSError, NotImplementedError) as exc:
print("符号链接未执行:", type(exc).__name__)
original.unlink()
assert hard.read_text(encoding="utf-8") == "hello"
if symlink_ok:
assert soft.is_symlink() and not soft.exists()
print("符号链接目标已删除,链接仍在")
print("硬链接保留内容:", hard.read_text(encoding="utf-8"))
Python 的 write 返回可能只把数据交给用户态缓冲;flush 把这些缓冲交给操作系统,也不能单独保证断电后保留。需要时先 flush,再 os.fsync 文件描述符,并检查异常。close 会正常刷新缓冲,但也不等于完整的崩溃持久性协议。进程崩溃时未交给 OS 的缓冲可能丢失;系统崩溃/断电还涉及内核和设备缓存、文件系统以及硬件承诺。
import os
from pathlib import Path
from tempfile import TemporaryDirectory
with TemporaryDirectory(prefix="g02-sync-") as tmp:
root = Path(tmp)
pending, target = root / "data.pending", root / "data.txt"
with pending.open("w", encoding="utf-8", newline="\n") as f:
assert f.write("finished\n") == 9
f.flush()
os.fsync(f.fileno())
os.replace(pending, target) # same directory; check failures in real use
assert target.read_text(encoding="utf-8") == "finished\n"
print("普通写入/同步/替换API核验;未模拟断电")
即使文件 fsync 成功,新建/替换名字涉及的目录元数据仍需单独考虑。Linux 上需要时对父目录描述符另做 fsync,且目标文件系统须支持;这套目录操作不能直接搬成 Windows 通用配方。原子替换的可见性与掉电后是否保留也不是同一保证。上例只核验正常 API 路径,没有测崩溃恢复或持久化保证。依据:Python pathlib 链接接口、os.fsync / replace、Linux fsync 与父目录。
🧩 六、Windows 路径的三个坑
① 反斜杠是转义符。
path = "C:\data\new\test.txt"
print(repr(path)) # 'C:\\data\new\test.txt' ⚠️ \n 和 \t 已经变成换行和制表符了
# ⚠️ 3.12 起解释器还会先打一行 SyntaxWarning: invalid escape sequence —— 别忽略它,那就是在报这个坑
⭐ 用原始字符串 r"C:\data\new",或者干脆用正斜杠 "C:/data/new" —— Windows 的 API 两种都收。
最好的办法还是 pathlib,它根本不需要你手写分隔符。
② 大小写不敏感。
import tempfile, os
d = tempfile.mkdtemp()
open(os.path.join(d, "Abc.txt"), "w").close()
print(os.path.exists(os.path.join(d, "abc.txt"))) # True ⚠️ 在 Linux 上是 False
💀 于是「本地跑得好好的,一上 Linux 服务器就 FileNotFoundError」。
⭐ 文件名一律小写是最省事的规避。
③ 长路径限制。 传统上限 260 字符。现代 Windows 可以解除,但别指望。
深层嵌套的输出目录容易踩到,症状是莫名其妙的 FileNotFoundError 而路径明明是对的。
Windows 的
CON、PRN、AUX、NUL、COM1等是保留设备名,带扩展名也应避免,例如con.txt。特殊路径命名空间下的个别行为不能当作可移植规则。参见 Microsoft 文件命名约定。
🧩 七、⭐ 相对路径相对于谁
import os, pathlib
print(os.getcwd()) # 当前【工作目录】
print(pathlib.Path(__file__).resolve().parent) # 脚本【自己】在哪
⚠️ open("data.txt") 找的是工作目录,不是脚本所在目录。
同一个脚本,cd 到项目根 跑和 cd 到脚本目录 跑,读到的是两个不同的文件(或者一个报错)。
⭐ 要读「和脚本放在一起」的文件,永远这么写:
import pathlib
HERE = pathlib.Path(__file__).resolve().parent
data = (HERE / "data.txt").read_text(encoding="utf-8")
💀 本项目在这上面栽过一次,而且极贵:构建脚本里写着
# 🧩 骨架:`os` 来自你自己的代码,这一段只看写法
ROOT = r"C:\desktop\claude" # 硬编码,指向【老位置】
SCRATCH = os.path.dirname(os.path.abspath(__file__)) # 跟着脚本走,指向【新位置】
项目搬进新仓库后,构建读的是新目录的源,却把产物写进了老目录。
⚠️ 为什么一直没发现:构建不报错、还照常打印「一切正常」的收尾行;
全套校验脚本全绿,因为它们的 ROOT 也硬编码成老目录、查的是同一份老产物。
唯一的破绽是产物的修改时间没变,而没人会去看。
实况是:改完一整轮内容、构建、跑完 8 个校验脚本全过,回头一扫才发现 107 个文件还是旧的。
⭐ 现在全项目一律写成:
import os
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) # 「本脚本上一级」
🔗 这一章连到哪里
| 相关的地方 | 为什么 |
|---|---|
| 08 · 环境、依赖和 import | 同样是「在我机器上好好的」,那一章管装什么,这一章管读什么 |
| 09 · 容器、哈希与顺序 | 另一个跨进程才暴露的坑:PYTHONHASHSEED 让 set 的遍历顺序每次都不同 |
| 数据这一关 · 04 · 脏数据的十种形态 | 那一章 owns 时区(全站讲得最密的一处)。⭐ 编码和时区是「数据看着对、其实错了」的两大源头 |
| AI 全栈 · 07b · 文件上传与对象存储 | 文件从用户手里到你磁盘上的那一段,编码和文件名的坑在那边还要再遇到一次 |
| SQL 查询这一关 · 附录A | 从 CSV 灌进数据库时,BOM 会让第一列名带上 \ufeff |
✅ 检查点
- Python 3.15 的文本
open()省略encoding时会怎么选?怎样核对实际选择? - 原 Windows 示例写入 UTF-8,报错为什么显示 GBK?换到 UTF-8 模式后,这次默认读取会怎么变?
- 带 BOM 的文件用
utf-8读出来,a.split(",")[0]为什么不等于"id"?怎么修? csv.writer写文件时不加newline="",字节层面会变成什么?为什么?- 原输出修复示例适用于怎样的标准流?
errors="replace"会牺牲什么? pathlib.Path("c.tar.gz").stem是什么?open("data.txt")找的是哪个目录?要读「和脚本放一起」的文件该怎么写?- 「硬编码 ROOT」那次事故,为什么 8 个校验脚本全绿却还是错的?
👀 答案
- 默认开启 UTF-8 模式时用 UTF-8,关闭后取区域编码。看该文本文件对象的
f.encoding可以确认。sys.getdefaultencoding()对应的是字符串编码 API 的默认值。 - 原运行未显式指定读取编码,按当地的
cp936解码才报 GBK 错误。切到 UTF-8 模式后,这份确实用 UTF-8 写成的文本可以按默认编码读出。 - 因为读出来是
'\ufeffid,name',第一列名实际是'\ufeffid'—— 而print出来看着一模一样。修法:读的时候用encoding="utf-8-sig"(没 BOM 时行为和utf-8一致,可以无脑用)。 - 变成
b'a,b\r\r\n'(两个\r)。因为csv模块自己写\r\n,而newline=None又把那个\n翻成\r\n。Excel 打开会每行之间多一个空行。一律加newline="",它的意思是「别动换行符,我自己管」。 - 原事故中的输出流无法用 GBK 表示 emoji。仅在自己控制的脚本里,接收端也约定 UTF-8 且原标准流有二进制
buffer时,才能照原示例替换输出流。errors="replace"遇到无法编码的内容会用替代标记,丢失原始字符。 c.tar,不是c。.stem和.suffix都只处理最后一个点;要完整的用.suffixes(['.tar', '.gz'])。- 找的是当前工作目录(
os.getcwd()),不是脚本所在目录。正确写法:HERE = pathlib.Path(__file__).resolve().parent,然后(HERE / "data.txt")。 - 因为校验脚本的
ROOT也硬编码成了老目录 —— 构建把产物写进老目录,校验脚本也去老目录查,两边对上了所以全绿。唯一破绽是产物 mtime 没变。现在一律用os.path.dirname(os.path.dirname(os.path.abspath(__file__)))。
先预测。 升级到默认开启 UTF-8 模式的 Python 3.15 后,用 open() 读取刚才那份旧文件,省略 encoding 会怎样?
👀 检查默认值和文件字节
这次默认选择 UTF-8,但文件仍是原来的 GBK 字节 D6 D0 CE C4,读取会抛 UnicodeDecodeError。若已确认来源是 GBK,仍应显式指定 encoding="gbk"。
本节回顾
⚡ 走神救援
先分清出问题的是文件内容、标准输出,还是文件位置。
open()的默认文本编码取决于 Python 版本、UTF-8 模式和系统区域设置;不能仅凭 Windows、Linux 或 macOS 判断。读写已知格式时,显式使用该格式约定的编码;下文 cp936 是原文环境的一次记录。第二个坑是 BOM:读出来的第一列名字前面多了一个看不见的字符,⭐ 打印出来完全正常,取列却报 KeyError 而列名看着一模一样。读用
utf-8-sig(没 BOM 时行为一致,可以无脑用),写给 Excel 也用它。💀 第三个坑是控制台编码,本项目真栽过:构建最后一步因为打印一个 emoji 抛编码错,崩在「旧图已删、新图未注入」的中间态上,而
except打印的是「不影响其他内容」——⭐ 在站点已经坏掉时报平安,全站图当场只剩一半。排查时单独核对实际输出流及接收方约定的编码。换行符上,csv 不加
newline=""会写出两个回车,Excel 里每行之间多一个空行。路径上:反斜杠是转义符、Windows 大小写不敏感(本地能跑、Linux 上找不到文件)、.stem只脱一层。⭐⭐ 最后一条最贵:相对路径相对于工作目录,不是脚本目录。 本项目硬编码根目录那次,构建读的是新目录的源,却把产物写进了老目录——💀 而八个校验脚本全绿,因为它们的根目录也硬编码成老的、查的是同一份老产物,一百多个文件的改动一个字都没进站点。⭐ 现在一律从
__file__推出根目录。
下一节 👉 附录A · 报错反查与速查