YAML 配置读错值:safe_load 悄悄改掉了八个字面量
TL;DR:YAML 规范只规定「这段文字是什么语法」,不规定「读进内存该是什么类型」——后者由 schema 决定。PyYAML 6.0.3 按 YAML 1.1 的隐式解析表走,ruamel.yaml 0.19.1 默认按 1.2 走。我实际跑了 19 个常见字面量,11 个(57.9%)两个库给出不同结果,其中 8 处完全不报错:no 变成 False、012 变成 10、1.0e3 变成字符串。等你发现的时候,这份配置已经生效过好几个版本了。
先分清两套类型系统,它们不是同一张表
很多人以为「YAML 解析」是确定性的:同一份文件,谁读都是同一个结果。不是。规范里真正定义隐式类型转换的只有 schema 那一节,而 1.1 与 1.2 的 schema 对同一批字面量给出的答案不一样。
YAML 1.1 的布尔类型页(yaml.org/type/bool.html,Working Draft 2005-01-18)把正则写得很宽:规范原文包含 y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF,并明确给出 canonical 形式是 y|n,还补了一句「may be abbreviated as a single character y/n or Y/N」。
YAML 1.2.2(Revision 1.2.2,2021-10-01)的 Core Schema 表把那串词砍掉了,布尔只剩三对大小写:true | True | TRUE | false | False | FALSE。整数表也换了写法:1.1 用前导 0 表示八进制,1.2 必须写 0o [0-7]+。浮点表更微妙,1.2 的 Core Schema 写的是 ([eE] [-+]? [0-9]+)?,指数符号是可选的。
于是问题来了:PyYAML 用的是 1.1 那张表。它的 resolver.py 里布尔正则字面量是 ^(?:yes|Yes|YES|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF)$,整数正则含 [-+]?0[0-7_]+(前导零八进制),浮点正则要求指数必须带符号 [eE][-+][0-9]+。ruamel.yaml 默认按 1.2 解析,官方 API 文档把 version 参数描述成「allow downgrading to YAML 1.1」——这句话反过来就说明默认不是 1.1。
一句话:你写的字面量没有歧义,是解析器的表不一样。
19 个字面量的实测矩阵
环境:Windows 11 + CPython 3.13.14 + PyYAML 6.0.3(2025-09-25 发布)+ ruamel.yaml 0.19.1。全部是本机实跑,不是从文档抄的。
| 文件里写的 | PyYAML 6.0.3 | ruamel.yaml 默认(1.2) | 结果 |
|---|---|---|---|
no | False | 'no' | 不同 |
on | True | 'on' | 不同 |
Yes | True | 'Yes' | 不同 |
y | 'y' | 'y' | 相同 |
012 | 10 | 12 | 不同 |
010 | 8 | 10 | 不同 |
0o12 | '0o12'(字符串) | 10 | 不同 |
08 | '08'(字符串) | 8 | 不同 |
0x1f | 31 | 31 | 相同 |
1:30 | 90 | '1:30' | 不同 |
12:00:30 | 43230 | '12:00:30' | 不同 |
1e3 | '1e3'(字符串) | 1000.0 | 不同 |
1.0e3 | '1.0e3'(字符串) | 1000.0 | 不同 |
1.0e+3 | 1000.0 | 1000.0 | 相同 |
1.10 | 1.1 | 1.1 | 相同 |
42_000 | 42000 | 42000 | 相同 |
2026-11-16 | datetime.date | datetime.date | 相同 |
~ | None | None | 相同 |
| 空值 | None | None | 相同 |
19 行里 11 行不同,占比 57.9%。注意「相同」不等于「安全」:1.10 两库都读成 1.1,y 两库都留成字符串——前者是值被改,后者是规范里本该是布尔却没被识别,两个方向的坑都在。
同一类问题在上一层也成立:JSON 的默认值同样决定「值长什么样」,可以对着 json、orjson、msgspec 的九个默认值实测 一起看。
把下面两行贴进命令行就能复现:
python -m pip install --target .\yamllib pyyaml==6.0.3 "ruamel.yaml==0.19.1"
set PYTHONPATH=.\yamllib
坑一:no 与 on 变成布尔值,而 y 与 n 反而没有
flag: no 在 PyYAML 里读出来是 False。如果你的代码是 if cfg['flag'] == 'no',这个分支永远不会进;如果代码是 if not cfg['flag'],那么用户写 no 就真的走了「假」分支,看起来一切正常——这正是最难查的那种:行为对了一半。
更绕的是 y 与 n。YAML 1.1 规范说它们是布尔,而 PyYAML 的布尔正则里根本没有单字母。实测:PyYAML 读 n 得 'n',ruamel.yaml 切到 1.1 模式读 n 得 False。也就是说,两个都自称支持 1.1 的实现,对于 1.1 明文列出的两个词给出相反答案。
这不是 bug,是历史决定。PyYAML 的 CHANGES 里 3.06 版有一条原文:「Fix the 'N' plain scalar being incorrectly recognized as !!bool」——它主动把单字母 N 从布尔里摘了出去。
修法只有一条可靠:任何「人写的词」都加引号。
features:
cache: "no"
telemetry: "off"
audit: false
引号会让解析器直接走 !!str,两个库都得到字符串 'no',谁也不猜。代价是布尔值必须写成真正的 false,不能靠单词。
坑二:012 是 10 还是 12,08 干脆变字符串
前导零在 1.1 里是八进制标记。012 在 PyYAML 是 10,在 ruamel 默认是 12——同一份文件,两个服务读到两个端口号。
010 更典型:PyYAML 给 8。而 08 不会报错,因为 8 不是八进制合法数字,PyYAML 的整数正则匹配失败,于是退化成字符串 '08'。同一段配置里 010 是整数、08 是字符串,类型静默分叉。
反向的坑同样存在:0o12 是 1.2 的写法,ruamel 读成 10,但 PyYAML 不认识 0o 前缀,原样返回字符串 '0o12'。你按新规范写,反而在老解析器里变成了字符串。
修法:配置里的编号、端口、版本号、工号一律加引号,或者彻底避免前导零。
坑三:1.0e3 是字符串,1.0e+3 才是浮点数
PyYAML 的浮点正则要求指数带符号:[eE][-+][0-9]+。所以 1.0e3 匹配失败,读出来是字符串 '1.0e3';写成 1.0e+3 才得到 1000.0。ruamel 按 1.2 的可选符号 [-+]?,两种写法都是浮点。
这个坑的杀伤力在于「看起来是数字」。字符串进了乘法会抛 TypeError: can't multiply sequence by non-int,进了 json.dumps 会变成带引号的数字,进了数据库会被当成文本排序。而配置文件本身没有任何问题。
修法:指数写成 1.0e+3,或者干脆写整数 1000。
坑四:1.10 变成 1.1,日期变成 date 对象
version: 1.10 读出来是 1.1。两个库都一样,因为这是 YAML 的浮点语义,不是 1.1/1.2 的分歧。发布号、镜像 tag、协议版本碰上这种写法就会静默降级。
日期同理:date: 2026-11-16 读出来是 datetime.date(2026, 11, 16),不是字符串。往下游传的时候,json.dumps 直接抛 TypeError: Object of type date is not JSON serializable,而 str() 之后格式又未必是你想要的。
修法:版本号与日期都加引号。要类型就让代码显式转换,不要让解析器替你决定。
坑五:重复键,一个取最后一个、一个取第一个、第三个直接报错
同一份文件里写了两次 a:
a: 1
a: 2
- PyYAML 6.0.3:
{'a': 2},静默取最后一个,无警告。 - ruamel.yaml 0.19.1 默认:抛
DuplicateKeyError。 - ruamel 设
allow_duplicate_keys = True:{'a': 1},取第一个。
三个答案。PyYAML 的选择是有据可查的,CHANGES 3.04 原文写着:「No longer check for duplicate mapping keys as it didn't work correctly anyway.」ruamel 的文档则直说:「PyYAML never enforced this although the YAML 1.1 specification already required this.」
这意味着一份「合并冲突没清干净」的配置,在 PyYAML 里表现为「后者覆盖前者」,在 ruamel 里表现为启动失败,在开了宽松开关的 ruamel 里表现为「前者胜出」。三套行为,没有一套会告诉你「这里有重复键」。
修法:把 ruamel 的严格默认值当成 CI 检查用——它会在合并前把问题拦住。
坑六:锚点别名是同一个对象,改一处等于改三处
YAML 的 &anchor 与 *alias 不是「复制一份值」,是「同一份值」。<< 合并键也一样,被合并进来的可变对象是共享引用。
实测:defaults: &d {retries: 3, tags: []} 被两个服务用 <<: *d 合并后,svc_a['tags'] is svc_b['tags'] 返回 True。给 svc_a 的列表 append 一个值,svc_b 与 defaults 里同时出现。
单进程里这是「省内存」,多线程里这是数据竞争,跨服务传出去之后就是「为什么 A 的配置改了 B 也变了」。
修法:读完立刻 copy.deepcopy;或者规定锚点下面只放标量,不放 list 与 dict。
坑七:文件头写 %YAML 1.2 也没用
有人以为在文件头加一行 %YAML 1.2 就能让 PyYAML 按新规范解析。实测不行:带 %YAML 1.2 指令的文件里,no 仍然读成 False、012 仍然读成 10——PyYAML 的隐式解析表是写死在 Loader 上的,不读指令。
ruamel 会读指令并切换解析规则:同一个文件里 no 保持 'no'、012 得 12,且 yaml.version 变成 (1, 2)。
修法:不要指望文件头。解析版本必须在代码里显式指定,并且写进 README——否则换个人换台机器,行为又变了。
坑八:写回文件时键被排序、中文被转义
读完改完写回去,yaml.safe_dump 的默认值是 sort_keys=True:{'b': 1, 'a': 2} 写出 a: 2 在前。配置仓库的 diff 会变成一片移动,review 时看不出真正的改动。
allow_unicode 默认 False:写 {'k': '中文'} 得到 k: "\u4E2D\u6587"。
有一个默认值是「帮忙」的:字符串 'no' 写回时会自动加引号成 'no',因为 dumper 知道不加引号它就会变成布尔——这点比很多库做得好。
修法:sort_keys=False 与 allow_unicode=True 一起显式写上;配置目录再加一条「只读不写」的约定。
「解析层悄悄改掉数据」不是 YAML 独有的现象,CSV 的字段与记录边界移动得更安静,见 CSV 的八个边界实测。
Troubleshooting:四个真实报错与修法
下面四条报错都是在本机复现出来的原文,不是「典型报错」示例。
报错一:Tab 缩进
现象:
yaml.scanner.ScannerError: while scanning for the next token
found character '\t' that cannot start any token
in "config.yaml", line 2, column 1
原因:YAML 的缩进只认空格,Tab 在任何位置都不能充当缩进。从网页或聊天窗口复制来的片段经常混着 Tab,肉眼看不出来。
修法:把文件里的 Tab 统一换成 4 个空格,改完再解析一次确认列号消失。
python -c "import io,sys; p=sys.argv[1]; s=io.open(p,encoding='utf-8').read(); s=s.replace(chr(9),' '); io.open(p,'w',encoding='utf-8',newline='').write(s)" config.yaml
报错二:一份文件里放了两个文档
现象:
yaml.composer.ComposerError: expected a single document in the stream
in "config.yaml", line 1, column 1
but found another document
in "config.yaml", line 2, column 1
原因:yaml.safe_load 只读第一个文档,遇到第二个 --- 直接报错。Kubernetes 清单、多环境配置常在一个文件里堆多个文档。
修法:改用 safe_load_all 并按需取,或者按 --- 拆成多个文件。
import yaml
docs = list(yaml.safe_load_all(open('config.yaml', encoding='utf-8')))
print(len(docs), type(docs[0]).__name__)
报错三:自定义标签没有构造器
现象:
yaml.constructor.ConstructorError: could not determine a constructor for the tag '!Foo'
in "config.yaml", line 1, column 4
原因:!Foo 是自定义标签,安全加载器只认标准标签。要么文件写错了,要么代码忘了注册构造器。
修法:确认到底需不需要这个标签;需要就显式注册,不需要就删掉标签。
import yaml
def foo(loader, node):
return loader.construct_scalar(node)
yaml.SafeLoader.add_constructor('!Foo', foo)
print(yaml.safe_load('k: !Foo bar'))
报错四:load() 少了 Loader 参数
现象:
TypeError: load() missing 1 required positional argument: 'Loader'
原因:PyYAML 6.0(2021-10-13)起执行了 PR #561「always require Loader arg to yaml.load()」。老代码里的 yaml.load(f) 直接失效。
修法:换成 yaml.safe_load(f)。不要为了省事去传 Loader=yaml.UnsafeLoader——5.4 起任意 Python 标签已经被挪进 UnsafeLoader,用它等于把配置文件当代码执行。
上线前的三条检查
第 1 条 · 加引号:所有「看起来像别的东西」的值——版本号、日期、编号、单词布尔——统统加引号。这一条能消掉上面八个坑里的六个。
第 2 条 · 双解析器对拍:CI 里用 PyYAML 与 ruamel 各读一遍,比较归一化后的结构(类型加值),不一致就失败。57.9% 的分歧率说明这一步不是洁癖。
第 3 条 · 断言类型而不是值:assert isinstance(cfg['port'], int),别只断言它等于 8080。类型错了,值对也没用。
把配置写回文件是另一个问题,两个进程同时改一份配置文件时该拿什么锁,见 跨进程文件锁实测。
FAQ
Q:我用的是 PyYAML,把配置全部加引号会不会影响别的服务?
加引号只改变「这段文字被解析成什么 tag」,不改文本内容。Go 与 Node 的解析器读加引号的字符串仍然是字符串,不会更差。真正的风险在于原本依赖隐式布尔的地方,需要一起改成显式 false。
Q:ruamel.yaml 是不是比 PyYAML 更安全?
在重复键这一项上是的,默认抛错。但它默认 1.2 也会带来新行为:012 变成 12、1e3 变成浮点。换库不等于换到「对」,只等于换到另一套规则,需要重新跑一遍对照。
Q:Python 3.13 上这两个库有什么已知问题?
本轮在 CPython 3.13.14 上双库全量跑通,用 pip install --target 装进隔离目录,未发现解析行为异常。PyYAML 6.0.3 发布于 2025-09-25,CHANGES 里 6.0.2 明确写了「Support for Cython 3.x and Python 3.13」。
Q:还有哪些值会被静默改写?
本轮只覆盖 19 个字面量。0b11、0x1f、1_0、~、.5、12. 也都在隐式解析表里,两个库结果一致但同样不是「你以为的字符串」。扩展测试请以官方 schema 表为准,建议查看 yaml.org 的 Core Schema 一节。
本文不含任何联盟推广链接;文中所有行为差异来自本机实跑,官方口径均标注了出处。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。