← 返回首页

YAML 配置读错值:safe_load 悄悄改掉了八个字面量

YAMLPyYAML配置解析

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 变成字符串。等你发现的时候,这份配置已经生效过好几个版本了。

// FLOW_01一次配置读取的五个落点5 NODES01STEP_01文件里写 k: no02STEP_02PyYAML safe_load 按 1.1 解析03STEP_03内存里得到 False04STEP_04代码判断 value == 'no' 恒假05STEP_05日志无异常,分支静默走错END_OF_FLOW
一次配置读取的五个落点 · 依据本文步骤自绘示意图
YAML 读取链路示意图:文件里的 k: no 经 safe_load 变成 False
YAML 读取链路示意图:文件里的 k: no 经 safe_load 变成 False · 依据本文主题生成的示意图
PythonJsonYaml
文中涉及的技术标识 · 图标来自 Simple Icons(CC0)

先分清两套类型系统,它们不是同一张表

很多人以为「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.3ruamel.yaml 默认(1.2)结果
noFalse'no'不同
onTrue'on'不同
YesTrue'Yes'不同
y'y''y'相同
0121012不同
010810不同
0o12'0o12'(字符串)10不同
08'08'(字符串)8不同
0x1f3131相同
1:3090'1:30'不同
12:00:3043230'12:00:30'不同
1e3'1e3'(字符串)1000.0不同
1.0e3'1.0e3'(字符串)1000.0不同
1.0e+31000.01000.0相同
1.101.11.1相同
42_0004200042000相同
2026-11-16datetime.datedatetime.date相同
~NoneNone相同
空值NoneNone相同

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 的选择是有据可查的,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 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页