JSON转Excel 使用教程
适用插件：JSON转Excel
本教程按插件 v1.0.0 的实际功能编写。
一、这个插件能做什么
JSON转Excel用于把一个或多个 .json 文件批量转换成 .xlsx 工作簿。它适合接口结果、数据集、日志导出和包含多层对象或数组的 JSON。
当前版本使用固定的“主记录 + 字段明细”结构：
每条主要记录只在“主记录”工作表占一行。
对象和数组按原始 JSON 路径逐项写入“字段明细”。
同一对象中的多个数组不会互相做笛卡尔组合，不会凭空制造不存在的数据关系。
超长字符串会按顺序分段，不会因为单元格字符上限而静默截断。
根级
meta、group_by等说明数据会保留，不会因提取results而丢失。写入使用压缩流式工作簿，转换后端运行在独立进程中；大文件转换不会占用工具箱主体的主事件循环。
插件只读取 .json，不会上传文件，也不会修改源 JSON。
二、使用前准备
建议准备两个不同的文件夹：
D:\待转换JSON
D:\转换后的Excel
开始前请确认：
JSON 文件不是空文件，并且能用文本编辑器正常打开。
文件使用 UTF-8 编码，中文显示正常。
JSON文件夹和Excel文件夹没有选反。
输出目录中的同名
.xlsx没有被 Microsoft Excel 或 WPS 占用。输出磁盘有足够空间和写入权限。
身份证号、订单号、银行卡号、设备编号等长编号在 JSON 中使用字符串，而不是数字。
长编号应写成：
{
"订单号": "202608091234567890"
}
如果写成 JSON 数字，解析时可能已经失去末尾精度，插件无法恢复原始数字。
三、进入插件和认识页面
打开吉米工具箱。
进入“本地应用”。
找到“JSON转Excel”并打开。
页面主要区域包括：
JSON文件夹：选择源文件所在目录。
Excel文件夹：选择
.xlsx保存目录。包含子文件夹：决定是否递归扫描下层目录。
加载文件：重新扫描并更新文件列表。
开始转换：启动当前队列。
暂停 / 继续：在当前文件的安全检查点暂停或恢复。
文件列表：查看每个文件的状态、进度、错误和结果路径。
返回：任务运行时会先提示是否取消并离开。
置顶：让插件页面保持在其他窗口前面。
文件列表每页可显示 10、20、50 或 100 条；这个设置只影响界面分页，不影响转换结果。
四、标准操作步骤
单击“JSON文件夹”右侧的“选择”。
选择存放源 JSON 的文件夹。
如果文件位于子目录，开启“包含子文件夹”。
检查文件列表和总文件数。
单击“Excel文件夹”右侧的“选择”。
选择结果保存目录。
单击“开始转换”。
等待每一行显示“已完成”和 100%。
打开输出目录，使用 Excel 或 WPS 检查结果。
建议先用一个代表性文件试转，确认工作表结构符合用途后再批量处理。
五、拖拽添加文件
可以把 JSON 文件、多个 JSON 文件或包含 JSON 的文件夹拖到页面：
拖到 JSON文件夹区域：设置源目录并加载文件。
拖到 Excel文件夹区域：设置输出目录。
拖到文件列表：把文件加入当前队列。
重复文件会去重。
开启“包含子文件夹”后，拖入文件夹会递归读取。
从不同盘符拖入且无法确定公共父目录时，页面会提示无法加入。
为了避免同名文件覆盖，建议把源文件整理到同一个总目录，并用子文件夹区分来源。
六、支持的 JSON 输入
1. 根数组
[
{ "编号": 1, "姓名": "张三" },
{ "编号": 2, "姓名": "李四" }
]
数组中的每一项是一条主记录，对应来源路径 /0、/1。
2. 带 results 的根对象
{
"meta": { "page": 1, "total": 2 },
"results": [
{ "编号": 1, "姓名": "张三" },
{ "编号": 2, "姓名": "李四" }
]
}
results 中每一项成为主记录；meta 等并列根级数据写入字段明细，范围为 root。
3. 普通根对象
没有 results 数组时，整个根值作为一条主记录，来源路径为空。
4. 单个基础值
根值可以是字符串、数字、布尔值或 null。它会在主记录中标明类型，并在字段明细中保存实际值。
5. 连续 JSON 和逐行 JSON
插件保留对连续 JSON 对象和每行一个 JSON 值的解析能力。标准 JSON 解析失败时才会尝试这些格式。重要数据仍建议使用完整、可校验的标准 JSON。
插件可以处理文件开头的 UTF-8 BOM 和部分非法控制字符。无法解析任何 JSON 值时会明确失败，不会生成一个看似成功的空结果。
七、“主记录”工作表
每条主要记录固定占一行。前 3 列固定为：
如果主记录是对象，它直接拥有的字符串、数字、布尔值和 null 字段会形成 字段:<字段名> 列。例如：
{
"results": [
{
"订单号": "O001",
"客户": { "姓名": "张三" },
"商品": [{ "名称": "水杯" }]
}
]
}
“主记录”会包含 字段:订单号，而嵌套的“客户”和“商品”进入字段明细。
直接字符串超过 Excel 单元格 32,767 字符时，主记录中的对应单元格留空，完整内容在字段明细中分段保存。这样既不截断数据，也不会让主表承担无限长文本。
八、“字段明细”工作表
字段明细固定为 7 列：
数组下标直接写入路径。例如：
/results/0/商品/0/名称
/results/0/商品/1/名称
JSON Pointer 中的特殊键会按标准转义：
字段名里的
~变为~0。字段名里的
/变为~1。控制字符、双引号和反斜杠按 JSON 字符串内容规则写成可识别的转义文本；“主记录”的
字段:<字段名>表头使用同一规则，既保留字段身份，也不会破坏 XLSX XML。
空容器也不会消失：
空数组保存为值类型
array、值[]。空对象保存为值类型
object、值{}。null保存为值类型null、空单元格值。
九、数组不会再互相组合
假设一条记录同时有 3 个商品和 2 个联系人。旧的二维展开方式可能生成 3 × 2 = 6 行，把互不相关的数组项组合在一起。
当前版本不这样处理：
商品按
/商品/0、/商品/1、/商品/2写入明细。联系人按
/联系人/0、/联系人/1写入明细。主记录仍然只有一行。
原始顺序和来源路径都能追踪。
因此，复杂 JSON 的结果不会因为多个独立数组而指数膨胀。
十、超长文本、公式文本和 Excel 边界
超长文本
Excel 单元格最多保存约 32,767 个字符。插件按安全边界把更长字符串拆成多行，并使用“分段序号 / 分段总数”记录顺序。代理对、中文和普通英文不会在分段边界被静默丢失。
公式样式文本
以 =、+、- 或 @ 开头的 JSON 字符串按普通文本写入，不会作为 Excel 公式执行。
工作表硬限制
单工作表最多 1,048,576 行。
单工作表最多 16,384 列。
路径和字段名也受单元格字符上限约束。
达到硬限制时转换会明确失败并显示原因，不会返回“已完成但只写了一部分”。
十一、输出文件规则
customers.json生成customers.xlsx。源目录中的相对子文件夹会在输出目录中保留。
每个结果固定包含“主记录”和“字段明细”两个工作表。
两张表首行冻结并对全部已生成列启用筛选。
XLSX 使用 Deflate 压缩，不再生成未压缩的超大工作表 XML。
写入先进入同目录的唯一临时文件；工作簿完整提交后才替换最终文件。
转换失败或取消只删除本次临时文件。
输出目录中已有的同名结果在新文件成功前保持不变；新文件成功后才被替换。
源 JSON 不会被移动、改名或删除。
十二、暂停、继续、取消和离开
暂停
单击“暂停”后，当前文件会在遍历或写入的下一个安全检查点暂停。大文件内部也会定期让出事件循环，因此不需要等待下一个文件才生效。
继续
单击“继续”后从当前安全位置恢复，不需要重新加载队列。
取消
任务运行或暂停时单击“返回”，页面会询问是否取消并离开：
选择不离开：任务保持当前状态。
确认离开：当前任务收到取消信号，未完成项目标记为“已取消”。
取消当前文件不会留下半成品最终文件，也不会破坏转换前已经存在的同名结果。
关闭插件、刷新全部插件、禁用插件或退出工具箱时，宿主会先停止新操作并等待独立转换进程真实结束；不会把旧任务的迟到进度写入后来加载的同名插件实例。
十三、实际示例
输入：
{
"meta": { "来源": "订单系统" },
"results": [
{
"订单号": "O001",
"金额": 99.5,
"客户": { "姓名": "张三" },
"商品": [
{ "名称": "水杯", "数量": 2 },
{ "名称": "签字笔", "数量": 3 }
],
"标签": []
}
]
}
“主记录”包含一行：
记录序号 = 1
JSON路径 = /results/0
值类型 = object
字段:订单号 = O001
字段:金额 = 99.5
“字段明细”包含：
root /meta/来源 订单系统
record /results/0/订单号 O001
record /results/0/金额 99.5
record /results/0/客户/姓名 张三
record /results/0/商品/0/名称 水杯
record /results/0/商品/0/数量 2
record /results/0/商品/1/名称 签字笔
record /results/0/商品/1/数量 3
record /results/0/标签 []
十四、常见问题
1. 选择文件夹后显示 0 个文件
检查扩展名是否为 .json，文件是否位于子目录，以及“包含子文件夹”是否开启。
2. 提示“未解析到 JSON 数据”
文件可能为空、不是 UTF-8、引号或括号不匹配，或者内容不是标准 JSON/逐行 JSON。请先用 JSON 校验工具修复。
3. 为什么不再生成多层合并表头
复杂对象数组无法无损地放入一张二维宽表。多数组组合会制造不存在的关系，动态对象键还可能产生数千列。当前版本使用固定关系长表，不提供层级宽表模式。
4. 为什么主记录某个字段为空，但字段明细里有内容
该字段可能是对象、数组，或者字符串超过单元格上限。完整内容应以字段明细为准。
5. 为什么一个长字符串出现多行
这是为了遵守 Excel 单元格字符上限。按“分段序号”从 1 开始拼接即可还原。
6. 输出文件打不开或转换失败
关闭占用同名文件的 Excel/WPS，确认输出磁盘空间和写入权限，再重新转换。失败信息会写入列表和工具箱统一 error.log。
7. 大文件转换时工具箱会不会卡住
转换运行在独立 utility process，工具箱主体仍可响应状态查询、暂停和取消。实际速度取决于 JSON 复杂度、字段数量、磁盘和杀毒软件扫描情况。
8. 独立转换进程崩溃后会怎样
当前文件失败，错误写入统一日志，进程不会在同一插件 record 上自动重启，半成品临时文件不会作为成功结果提交。重新加载插件后可以重新转换。
十五、数据安全与风险提示
转换逻辑只在本机读取和写入，不上传 JSON 内容。
Excel 会保留源 JSON 中的姓名、手机号、身份证号、地址、订单等敏感字段，请妥善保管结果。
不要在转换时拔出移动硬盘、断开网络盘或强制关机。
长编号必须在源 JSON 中使用字符串。
容错解析只用于识别常见 BOM、控制字符、连续 JSON 和逐行 JSON；重要数据应优先修复为标准 JSON。
工作表达到 Excel 硬限制会失败，需要先拆分源文件，不能通过增加内存绕过。
十六、完成前检查清单
转换前：
源文件扩展名为
.json。文件为 UTF-8，JSON 已通过格式校验。
长编号已保存为字符串。
已确认是否需要递归子文件夹。
输入和输出目录没有选反。
同名 Excel/WPS 文件已关闭。
输出磁盘有足够空间。
转换后：
文件列表显示“已完成”和 100%。
工作簿包含“主记录”和“字段明细”。
主记录数符合预期。
根级
meta等字段仍可在明细中找到。数组下标和 JSON 路径可追溯。
超长文本分段完整。
工作簿可以被 Excel/WPS 正常打开。
敏感结果已保存到安全位置。
评论区