pd.json_normalize()处理字典列需先转为列表：df['col'].tolist()，且record_path必须为列表（如['items']）；否则报KeyError、返回空DF或TypeError。
pd.json_normalize() 处理字典列时直接报错 KeyError 或返回空 DataFrame
常见现象是：DataFrame 里有一列存的是 Python 字典（不是 JSON 字符串），但直接传给 pd.json_normalize() 就出错，比如 KeyError: 'id'，或者结果全是 NaN。这是因为 pd.json_normalize() 默认只接受 list of dict，不接受单个 dict 或含 dict 的 Series。
- 先确认列类型：
df['col'].apply(type).unique()—— 如果看到 - 必须把字典列转成列表：
pd.json_normalize(df['col'].tolist())，不能写pd.json_normalize(df['col']) - 如果列里混了 None、NaN 或非 dict 类型，
.tolist()会保留它们，导致json_normalize报错；需提前清洗：df['col'].dropna().apply(lambda x: isinstance(x, dict)).all()检查，再用df['col'].dropna().tolist()
嵌套字典展开后字段名带点号（如 user.name），想改成下划线或去掉层级
默认展开后字段是 user.name、address.city 这种点分隔形式，Pandas 不允许点号作为列名（虽然实际能存，但后续用 df.user.name 会失败），而且也不符合多数数据库或导出规范。
- 用
sep参数换分隔符：pd.json_normalize(data, sep='_')→ 得到user_name、address_city - 想完全扁平化（去掉所有嵌套标识），只能手动重命名，
json_normalize本身不支持；可接.rename(columns=lambda x: x.rsplit('.', 1)[-1])，但注意同名字段会冲突（比如两个不同层级都有id） -
max_level控制展开深度，设为0就不展开任何嵌套，设为1只展开一层 —— 对深层嵌套很实用，避免爆炸式列增长
处理含列表的嵌套结构（如 "tags": ["a", "b"] 或 "items": [{"id":1}, {"id":2}]）
遇到字段值是 list，json_normalize 默认会把整个 list 当成一个单元塞进单元格，不会自动“炸开”。要真正展开，得靠 record_path 和 meta 配合。
- 若目标是展开
items列表（每个元素是 dict）：pd.json_normalize(df, record_path=['items'], meta=['id', 'name'])，其中record_path指定要“压平”的路径，meta是想保留的外层字段 - 若字段是简单 list（如
["a","b"]），json_normalize无法直接展开；得先用explode()：df.explode('tags').reset_index(drop=True)，再对单个 tag 做后续处理 - 注意
record_path必须是 list 路径，写成字符串（如'items'）会报TypeError；正确写法是['items']或['data', 'items']
性能差、内存暴涨：大 DataFrame 上反复调用 json_normalize
别在循环里对每一行做 json_normalize(row['col']) —— 这会触发上千次小规模 normalize，开销远高于一次性处理整个列表，还容易因 dtype 不一致导致隐式转换和内存碎片。
- 始终优先批量处理：
pd.json_normalize(df['col'].dropna().tolist())，而不是逐行 - 如果字典列里有大量 null 或结构不一致，
json_normalize内部会填充 NaN 并推断 dtype，可能把 int 列变 float；可在之后用.convert_dtypes()或显式.astype()修正 - 超大 JSON（单条 >1MB）建议先用
json.loads()验证合法性，避免json_normalize在中间崩溃导致整批失败
事情说清了就结束。最常被忽略的是：字典列必须转 tolist() 才能喂给 json_normalize，以及 record_path 必须是列表而非字符串 —— 这两个点卡住的人最多。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
