json_normalize比手写递归更可靠，因其内置处理None、空列表、混合类型等边界情况，并按record_path和meta精准提取结构化记录与上下文字段。
json_normalize 为什么比手写递归更可靠
因为嵌套结构千变万化，手写 flatten 容易漏掉 None、空列表、混合类型字段（比如某次是 dict，下次变成 list），而 json_normalize 内部已处理这些边界情况。它不是“展平所有键”，而是按你指定的 record_path 和 meta 路径做结构化提取——这恰恰是多数真实场景需要的：从嵌套中精准捞出记录行 + 携带上下文字段。
record_path 不是路径字符串，而是字段名或路径列表
record_path 必须指向一个可迭代对象（通常是 list），否则会报 TypeError: record_path is not a list or string。常见错误是直接传 "data.items" 这种点号路径——json_normalize 不支持点号语法，只认字面字段名或嵌套路径列表。
- ✅ 正确：
record_path=["data", "items"]（表示先取data字段，再取其下的items列表） - ✅ 正确：
record_path="items"（如果顶层就是items列表） - ❌ 错误：
record_path="data.items"或record_path="data/items" - ⚠️ 注意：如果
data是None，该行会被跳过，不会报错——这是默认容错行为，但可能掩盖数据缺失问题
meta 参数要小心字段层级和重名冲突
meta 用来提取每条记录的“父级信息”，比如订单ID、时间戳。但它不自动加前缀，若 meta 字段和 record_path 内字段同名，后者会覆盖前者。
- 用
meta_prefix加前缀避免冲突：meta_prefix="order_"，这样id就变成order_id -
meta支持混合写法：meta=["id", ["user", "name"], ["metadata", "source"]]，其中["user", "name"]表示从user对象里取name - 如果某个
meta路径不存在（如user缺失），对应单元格为NaN，不会中断整个转换
遇到 list-of-dict 但没外层 record_path 怎么办
如果你的数据本身就是 [{"a": 1, "b": {"c": 2}}, ...] 这种 list，没有包装字段，别硬凑 record_path。直接传入 list，json_normalize 默认把它当记录集处理：
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
import pandas as pd
from pandas import json_normalize
<p>data = [{"id": 1, "info": {"name": "Alice", "tags": ["dev"]}}, {"id": 2, "info": {"name": "Bob"}}]
df = json<em>normalize(data, sep="</em>") # 自动展开 info.name → info_name这时候 sep="_" 很关键：它控制嵌套键的连接符，默认是 .，但 . 在列名里容易和 Pandas 方法冲突（比如 df.info.name 会误触发方法调用），所以建议统一用 _。
真正难的是字段值本身又是 list（比如 "tags": ["dev", "py"]）——json_normalize 不会展开 value-level 列表，它只会把整个 list 当成一个单元格内容。需要后续用 explode() 单独处理，这不是 json_normalize 的职责。
