必须指定 record_path 当 JSON 中需转行的数据藏于多层嵌套列表中，如 ["data", "items"]；需用 meta 保留父级字段，errors="ignore" 处理缺失；混合类型列表须预处理为统一 dict 结构，不规整嵌套应先递归清洗再归一化。

直接用 pandas.json_normalize()，但默认行为对深层嵌套、混合类型（如列表内含字典）、重复键处理很不友好——得手动控制 record_path、meta 和 errors 参数，否则会丢数据或报错。

什么时候必须指定 record_path？

当你的 JSON 里真正要转成行的数据藏在多层嵌套的 list 里（比如 {"data": {"items": [{"id":1}, {"id":2}]}}），json_normalize() 默认只展开顶层，根本看不到 items。

• 不设 record_path：返回空 DataFrame 或只有一列 data
• 设 record_path=["data", "items"]：正确提取两个对象为两行
• 如果 items 有时是 null 或缺失，加 errors="ignore"，否则直接抛 KeyError

如何保留父级字段（如 ID、时间戳）？

光展平子列表不够，你还得把外层上下文带进来，比如每个 item 对应的 order_id 或 batch_time。这时候靠 meta 参数。

wechat-article-extraction-mp-weixin-qq-com news-webpage-cleaning blog-post-parsing metadata-extraction-title-author-date multiple-output-formats-markdown-json-plain-text batch-processing-support

基于三引擎设计，从微信文章、新闻和博客网页提取干净内容，支持标题作者日期元数据，多格式和批量处理。

下载

• meta 接一个字段路径列表，例如 ["data", "order_id"] 或 ["meta", "timestamp"]
• 路径可以比 record_path 更深，也能跨兄弟节点（只要最终能定位到值）
• 如果某个 meta 路径在某些记录里不存在，同样要配 errors="ignore"，否则整批失败

遇到列表里混着标量和字典怎么办？

json_normalize() 遇到 [1, {"a":2}, null] 这种 heterogenous list 会直接报 TypeError: unhashable type: 'dict'——它期望 list 里全是 dict。

立即学习“Python免费学习笔记（深入）”；

• 先用 Python 预处理：遍历原始 JSON，把非 dict 元素统一转成 dict（如 1 → {"value": 1}）
• 或者用 max_level 限制递归深度，避免误展开不该拆的 list
• 更稳的做法：用 pd.json_normalize(data, max_level=0) 先全当字符串读入，再对具体列用 apply(json.loads) 二次解析

最麻烦的不是嵌套深，而是嵌套“不规整”：同一字段在不同记录里可能是 dict、list、string 或 null。这种情况下，别硬扛 json_normalize，先写个递归清洗函数做 schema 对齐，再进 pandas。否则列名冲突、类型错乱、NaN 爆满，调试成本远高于多写十行预处理。