直接调用pandas.json_normalize()是最稳妥起点，它专为嵌套json设计，能自动展开字典与列表混合结构，但默认仅展平一层，深层字段需配合record_path、meta等参数显式指定路径，并注意输入必须为python对象而非json字符串。
用 pandas.json_normalize() 处理多层嵌套 JSON
直接调用 pandas.json_normalize() 是最稳妥的起点，它专为嵌套 JSON 设计，能自动展开字典、列表混合结构。但注意：默认只展平一层，深层字段（比如 "user.profile.address.city"）不会自动递归解析。
常见错误是传入原始 JSON 字符串——必须先 json.loads() 成 Python 对象；还有人把整个 JSON 列表当单个 dict 传，结果报 TypeError: expected string or bytes-like object。
- 如果顶层是列表（常见于 API 响应），直接传给
json_normalize() - 如果顶层是 dict 且数据藏在某个 key 下（如
"data"），用record_path指定路径，比如record_path=["data", "items"] - 用
meta参数提取上层字段作为列，例如meta=["id", ["user", "name"]]可同时拉出id和嵌套的user.name
手动递归展平时如何避免键名冲突
当嵌套结构不规则（比如同一层级有 list 和 dict 交替）、或需要完全控制列名时，手写递归函数更可靠。关键问题不是“怎么递归”，而是“怎么命名中间键”——不同分支的同名字段（如两个 "id"）会覆盖。
推荐用下划线连接路径，而不是点号（.），因为点号在 pandas 列操作中容易引发语法歧义（比如 df.user.id 会误读）。另外，空值和缺失键要统一处理为 None，否则 pd.DataFrame() 构造时可能报 ValueError: All arrays must be of the same length。
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 递归函数里用
sep="_"拼接键名，例如"config_timeout"而非"config.timeout" - 遇到 list 时，对每个元素单独递归，并保持外层键前缀（如
"tags_0","tags_1"） - 始终检查
isinstance(value, (dict, list))，别假设所有 value 都可迭代
json_normalize() 的 max_level 和性能陷阱
max_level=1 是默认值，意味着只展开一级嵌套。设成 2 或更高看似能“全自动”，但实际很少有用——它只控制字典展开深度，对 list 内部的 dict 无效，且容易生成大量稀疏列（比如每个用户有不同数量的 skills，就会产生 skills_0_name, skills_1_name 等一堆带编号的列）。
真正影响性能的是 record_path 是否指向高基数 list（比如一个订单含 500 行子项）。这时 json_normalize() 会复制外层 meta 字段 500 次，内存暴涨。此时应分步处理：先用 json_normalize(meta=[...]) 提取主表，再对子列表单独 normalize 并用 merge 关联。
- 不要盲目提高
max_level，优先用record_path+meta显式声明结构 - 若子列表过长，考虑加
errors="ignore"跳过解析失败项，避免中断 - 用
dtype=object初始化 DataFrame 可减少类型推断开销，尤其字段值类型混杂时
导出表格前必须检查的三类字段异常
展平后直接 to_csv() 很容易踩坑：看似整齐的 CSV，打开后某列全是 repr(dict) 字符串，或者时间字段变成 Timestamp 对象导致 Excel 无法识别。根本原因是 pandas 对复杂对象（如嵌套 dict、datetime、Decimal）做了隐式转换，但没报错。
- 遍历
df.dtypes，把object类型列用df[col].apply(type).unique()检查是否混入了 dict/list —— 若有，说明该列没被彻底展平 - 对疑似时间字段，用
pd.api.types.is_datetime64_any_dtype()确认，必要时用dt.strftime()转字符串 - 含中文或特殊符号的键名，在 CSV 中可能乱码，导出务必加
encoding="utf-8-sig"
嵌套 JSON 展平不是“运行一次就完事”的操作，真实数据里总有意外结构冒出来——最省事的方式，是每次解析后立刻用 df.info() 扫一眼非空计数和 dtype，比事后调试快十倍。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
