应捕获 yaml.YAMLError 并用 e.problem_mark 定位行列错误，校验空内容和多文档，强制使用 safe_load() 和结构校验库。
捕获 yaml.YAMLError 时别只看错误字符串
直接 str(e) 打印异常，往往只看到“while scanning for the next token”这类模糊提示，真正有用的是 e.problem_mark——它明确指出第几行、第几列出的问题。缩进错一位、漏一个冒号、字符串里混了未引号的 {，全靠它定位。
必须用 try/except yaml.YAMLError as e: 包裹解析逻辑，而不是只捕获 Exception；否则像 FileNotFoundError 或 UnicodeDecodeError 会被一并吞掉，掩盖真实问题。
- 打印时优先输出
e.problem_mark.line + 1和e.problem_mark.column + 1（YAML 行列从 0 开始计数，人类习惯从 1） - 如果
e是yaml.scanner.ScannerError，大概率是缩进或字符非法；如果是yaml.parser.ParserError，多为结构嵌套错乱（比如key:后没内容又没换行） - 编辑器开启“显示空白字符”，能立刻暴露空格和 Tab 混用——这是最常被忽略的根源
空内容、多文档、注释文件必须单独兜底
yaml.safe_load() 遇到空文件、纯注释（只有 # 行）或开头就是 --- 但后面没内容，会安静地返回 None。后续代码若直接对返回值做 .get('db')，立刻抛 AttributeError，和 YAML 格式无关，但错误堆栈会误导你。
- 加载前加一层校验：
if not data.strip(): raise ValueError("YAML content is empty") - 要读全部
---分隔的文档，必须用list(yaml.safe_load_all(data))，不能用safe_load()——后者只取第一个 - 简单场景可写成
yaml.safe_load(stream) or {}，比 try/except 更轻，但仅适用于配置必有默认值的场合
永远不用 yaml.load()，除非你在本地调试
生产环境用 yaml.load() 等同于给攻击者留后门。!!python/object:os.system 这类标签能直接执行系统命令，PyYAML 官方早在 2017 年就明确警告过。安全边界必须一刀切：可信来源也走 safe_load()。
立即学习“Python免费学习笔记（深入）”；
- 真需要自定义标签（如
!include），必须自己写Constructor并显式注册，禁用FullLoader - 开发阶段临时排查，可用
yaml.load(data, Loader=yaml.FullLoader)获取更详细的 token 流信息，但代码提交前必须删掉或替换 -
yaml.CSafeLoader比默认SafeLoader快，行为一致，建议显式指定：yaml.safe_load(stream, Loader=yaml.CSafeLoader)
结构校验别塞在 YAML 层，交给专用库
有人试图用 !!int 或 !!bool 强制类型，或在 YAML 里写冗长注释说明“此字段必填”，这既难维护又不生效——safe_load() 无视所有标签，注释也不进数据结构。
校验逻辑该放在解析之后：用 pydantic.BaseModel 或 voluptuous.Schema 声明字段名、类型、默认值、是否必需。YAML 只管提供原始数据，校验失败时的报错信息自带路径（如 database.port: expected int, got str），比 YAML 解析错误更容易修复。
- 避免在
safe_load()后写一堆if 'host' not in cfg.get('database', {}): raise ... - 不要为了绕过校验，在 YAML 里塞
port: "5432"再手动int()——类型该由 schema 保证，不是靠人眼盯
最麻烦的不是语法错，而是空内容被当成有效配置、多文档被 silently 截断、或者校验逻辑散落在各处导致改一处漏十处。这些点不提前卡死，后期排查成本远高于写几行防御代码。
