Excel转JSON工具exe环境配置与问题排查全指南

简介这是一款面向开发者与数据处理人员的Excel转JSON桌面小工具以exe可执行程序形式提供解决Excel表格数据向JSON格式快速迁移的问题适用于API接口开发、数据交换与自动化脚本处理等场景无需编程基础即可上手。资源包共31个文件约5.44MB包含2个exe可执行文件、2个dll动态库、12个h头文件与3个cpp源文件以及sln解决方案、vcxproj工程文件等Visual Studio项目配置另附说明文档与图标资源兼顾直接运行与源码二次开发两种使用方式。目前已有1021人学习下载。工具支持导入Excel文件、设置转换范围与格式参数、一键生成并保存JSON文件并针对数值、日期、布尔值等数据类型差异及空白行列清理给出处理思路帮助读者理解行与对象、列与属性、工作表与数组的对应关系提升数据转换效率。1. 一个 exe 双击没反应让我把 Excel 转 JSON 的链路重装了一遍上周帮一个做数据清洗的朋友配环境他要把一批带合并单元格的 Excel 表转成 JSON 喂给前端。他下载了一个 excel转json 的 exe 工具双击之后窗口一闪就没了任务管理器里连进程都没留下。我远程过去看了十分钟问题不在工具本身而在他机器上缺了运行库加上 Excel 文件里有一列日期格式被识别成了浮点数。这类 excel2json、exceltojson 的小工具看起来是「下载即用」实际上对系统环境、文件结构、编码都有隐性要求装不好就是双击无响应、转出来乱码、字段全变 null。这篇记录的是我重新把这套 Excel 转 JSON 的 exe 工具环境从零配到能稳定跑通的完整过程适合正在找 excel 转 json 工具、卡在 exe 打不开或转换结果不对的开发者照着走一遍。2. 装前先把环境列清exe 工具不是双击就完事2.1 系统版本与运行库的对应关系这类 Excel 转 JSON 的 exe 工具绝大多数是用 .NET 或 Python 打包出来的单文件程序。打包方式决定了它依赖什么运行库。我一般先看文件体积和属性如果 exe 在 10MB 以内大概率是 .NET 编译的需要对应版本的 .NET Desktop Runtime如果超过 30MB可能是 PyInstaller 打包的 Python 程序理论上自带解释器但仍然依赖系统的 Visual C 运行库。常见做法是先确认系统版本再决定装哪个运行库。下面这条命令用来查看当前 Windows 的版本和内部版本号方便对照运行库要求# 查看 Windows 版本与内部版本号用于对照 .NET 运行库要求 winver # 或者在 PowerShell 里取更细的版本信息 [System.Environment]::OSVersion.Versionwinver弹窗里的版本号对应关系要记一下Windows 10 1809 以上才支持 .NET 6 的桌面运行时Windows 7 最高只能到 .NET Framework 4.8。如果 exe 是用 .NET 8 打包的在 Win7 上无论怎么装都跑不起来这不是配置问题是硬性不支持。我遇到过有人在一台 Win7 机器上反复重装运行库最后发现工具本身要求 Win10 起步白折腾两小时。Visual C 运行库这块我一般直接装 2015-2022 的合并版x86 和 x64 都装上。原因是很多 exe 虽然是 64 位系统上运行但打包时链接的是 32 位的运行库只装 x64 版本会出现「找不到 VCRUNTIME140.dll」的报错。这个坑很玄学同一个工具在 A 机器能跑、B 机器报缺 dll差别往往就在这里。2.2 版本选择单文件版和带依赖目录版的取舍下载页面通常会给两个包一个是单个 exe一个是压缩包里带一堆 dll 的目录版。新手容易只拿单文件版觉得干净。我的经验是如果单文件版双击没反应优先换目录版试一次因为目录版把依赖都摊在明面上缺什么 dll 系统会直接报文件名比单文件版一闪而过好排查得多。版本号这块excel2json 类工具迭代不算快但要注意区分「支持 .xls 老格式」和「只支持 .xlsx」的版本。有些新版本为了减小体积去掉了对 .xls 的解析库如果你的源文件是老的 .xls转出来会直接报格式不支持。我一般会保留一个旧版本放在旁边遇到 .xls 就换旧版跑遇到 .xlsx 用新版两个版本共存不冲突改个文件名区分就行。提示下载后先别急着双击右键看属性里的「数字签名」和「详细信息」标签能确认打包框架和版本号比盲目试运行省时间。2.3 目录规划与权限别放在 Program Files 下exe 工具我从来不放在C:\Program Files下面。原因很简单那个目录默认需要管理员权限写入而这类转换工具往往会在同目录下生成临时文件、日志或者缓存配置。放在 Program Files 下普通权限运行时写临时文件失败表现就是转换到一半卡住或者输出空文件。我一般建一个独立目录路径里不带中文和空格# 建立独立工作目录路径避免中文和空格 mkdir -p /d/tools/excel2json/bin mkdir -p /d/tools/excel2json/input mkdir -p /d/tools/excel2json/output这是 Git Bash 下的写法对应 Windows 的D:\tools\excel2json。bin放 exe 本体input放待转换的 Exceloutput放生成的 JSON。分开的好处是转换命令里路径固定不用每次敲一长串也避免输出文件把源目录搞乱。路径带中文是另一个高频翻车点某些打包工具对 Unicode 路径处理不干净读文件时直接抛异常表现同样是闪退。3. 安装与首次运行把 exe 跑起来的三步3.1 解压、放置与依赖补齐拿到压缩包后先解压到bin目录不要直接在压缩软件里双击运行。压缩包内直接运行 exe程序的工作目录会被设成临时解压目录生成的配置文件下次就找不到了表现是每次打开都要重新配置。解压后目录结构大概是这样我按实际会看到的文件列一下文件/目录作用是否必须excel2json.exe主程序必须*.dll依赖库目录版必须单文件版无config.ini默认配置可选首次运行生成logs/运行日志可选排错时看如果双击后提示缺少某个 dll按提示的文件名去补对应的运行库。缺VCRUNTIME140.dll或MSVCP140.dll就装 VC 2015-2022 运行库缺hostfxr.dll或coreclr.dll说明是 .NET 程序装对应大版本的 Desktop Runtime。装完运行库必须重启一次不然环境变量没刷新程序还是找不到。3.2 命令行参数跑通第一次转换图形界面点按钮虽然直观但排查问题时命令行更可控能看到具体报错。这类工具一般支持命令行调用常见参数是输入文件、输出文件、工作表名。下面这条是我常用的最小调用# 进入工具目录执行一次最小转换 cd /d/tools/excel2json/bin ./excel2json.exe --input ../input/sample.xlsx --output ../output/sample.json --sheet Sheet1参数含义--input指定源 Excel 路径支持相对路径--output指定输出 JSON 路径目录必须已存在工具不会自动建目录--sheet指定工作表名不写默认取第一个工作表。第一次跑建议用一张结构简单的表两三列、几行数据确认链路通了再上复杂表。如果这条命令报「unknown argument」说明这个版本不支持命令行只能走图形界面那就退回双击运行但工作目录仍然保持在 bin 下。转换成功后打开输出的 JSON重点看三件事字段名是不是表头、数值列有没有被加引号、中文有没有变成\uXXXX。前两个决定下游能不能直接用第三个看工具是否有编码选项。有些版本默认输出 ASCII 转义需要在配置里关掉。3.3 配置文件里三个关键项首次运行后 bin 目录下会生成 config.ini 或类似配置文件用文本编辑器打开重点改三项。第一项是编码把输出编码设成 UTF-8避免中文转义第二项是空单元格处理选 null 还是空字符串这个直接影响前端判空逻辑第三项是日期格式Excel 里的日期在底层是数字不指定格式会转成 45000 这种序列号。; config.ini 关键项示例 [output] encoding utf-8 ; 输出编码避免中文转义 empty_as_null true ; 空单元格输出 null前端好判空 date_format yyyy-MM-dd ; 日期列按此格式输出字符串encoding改成 utf-8 后中文直接以原字符写入文件体积略大但可读empty_as_null设 true 时空单元格在 JSON 里是null设 false 则是两种下游处理方式不同按项目约定选date_format只对识别为日期的列生效如果某列被误判成数字需要回到 Excel 里把单元格格式改成文本再转。改完配置保存重新跑一次 3.2 的命令验证。4. 转换参数调优字段映射与类型推断4.1 表头行与数据起始行的指定实际业务表很少是第一行就是干净表头经常上面有标题、说明、合并单元格。这类工具一般提供表头行号和数据起始行号两个参数。我常用的组合是表头在第 3 行、数据从第 4 行开始# 指定表头行与数据起始行跳过前两行说明 ./excel2json.exe --input ../input/report.xlsx --output ../output/report.json \ --header-row 3 --data-start-row 4 --sheet 数据--header-row 3表示第 3 行作为字段名来源--data-start-row 4表示从第 4 行开始读数据。两个参数要配合用只设表头行不设数据起始行工具可能把表头上方的说明行也当数据读进去输出里多出几条脏记录。工作表名带中文时命令行要加引号或者确认终端编码Git Bash 下一般没问题cmd 下可能需要切到 UTF-8 代码页。4.2 数值与文本的类型推断规则Excel 单元格没有严格类型一个看着像数字的列可能混着文本和空值。工具的类型推断通常是「整列采样判断」如果一列里超过一定比例是数字整列按数字输出个别文本会被转成 null 或跳过。这个规则在混合列上容易翻车比如编号列里混了001这种带前导零的值按数字输出就变成1前导零丢了。我的处理办法是对编号、电话、身份证这类列在 Excel 里先把整列格式设成文本再转。工具读到文本格式的单元格会原样输出字符串不做数值转换。如果不想改源文件看配置里有没有「强制文本列」的选项常见写法是列名列表; 强制按文本输出的列避免前导零丢失和长数字精度问题 [types] force_text_columns 编号,电话,身份证号force_text_columns里写列名逗号分隔。长数字还有精度问题超过 15 位的数字在 JSON 里如果按数值存末尾会丢精度强制文本是最稳的做法。这一项在数据清洗场景里几乎是必配不配的话下游拿到错误编号排查起来很费劲。4.3 合并单元格与多级表头的处理合并单元格是 Excel 转 JSON 的老大难。工具读到合并区域通常只在左上角单元格有值其余是空。如果表头是两行合并的多级表头直接转出来字段名会缺一半。常见做法是先在 Excel 里取消合并并填充或者用工具的多级表头参数。我一般优先在源文件处理选中合并区域取消合并然后 CtrlG 定位空值输入公式引用上方单元格批量填充。这一步在 Excel 里两分钟搞定比在工具里调参数稳。如果表数量大不想手工改看工具是否支持--merge-header之类的参数把多级表头拼成一级_二级的字段名。这个参数各版本叫法不一用--help查一下实际名称再写别照抄网上的参数名版本对不上会直接报错。5. 常见问题排查闪退、乱码、字段丢失5.1 双击闪退且无日志现象双击 exe 窗口一闪而过bin 目录下没有 logs 文件夹事件查看器里也找不到明显记录。原因多数是缺运行库程序在加载阶段就失败来不及写日志。少数是 exe 被杀毒软件拦截后静默终止。解决先在命令行里运行 exe报错会直接打在终端上比双击多一层信息。如果命令行也秒退去「事件查看器 → Windows 日志 → 应用程序」里找对应时间点的错误会写明缺哪个 dll 或哪个 .NET 版本。按提示补运行库补完重启。杀毒软件拦截的话把工具目录加进信任列表别直接关杀毒。5.2 输出 JSON 中文变成转义序列现象生成的 JSON 里中文全是\u4e2d\u6587这种形式文件能解析但人看不懂某些下游直接当字符串处理会出问题。原因输出编码默认走了 ASCII 转义配置里没设 UTF-8。解决改 config.ini 的encoding utf-8重新转换。如果配置里没有这一项看命令行是否支持--encoding utf-8。改完用文本编辑器打开确认中文正常显示再用 JSON 解析器校验一遍确保没有因为编码切换产生非法字符。5.3 某列数据全部为 null现象转换成功但某一列在 JSON 里全是 nullExcel 里明明有值。原因三种可能。列名重复导致后者覆盖前者该列被类型推断判成数字但实际是文本表头行号设错读到了空行当表头。解决先打开输出的 JSON 看字段名对不对字段名错了就是表头行号问题调--header-row。字段名对但值全空检查 Excel 里该列是否有隐藏字符或前后空格清理后重转。列名重复的话在 Excel 里给重复列改名或者在工具配置里开启重复列重命名选项常见是自动加后缀_2。5.4 大文件转换中途卡死或内存溢出现象几万行的 Excel 转换到一半进程消失或者卡住不动。原因工具一次性把整个工作簿读进内存行数多、列数宽时内存不够或者是 32 位程序有内存上限。解决优先换 64 位版本。没有 64 位版就拆分源文件按行数切成多个小表分别转再用脚本合并 JSON。拆分时注意表头每份都要保留不然合并后字段对不齐。我一般按 2 万行切一份这个量级大多数工具都能扛住。注意拆分和合并的脚本要单独验证一次字段顺序不同批次转出来的 JSON 字段顺序可能不一致合并前统一按字段名排序避免下游解析错位。6. 装完怎么验证跑通三张表加一次回归验证这套 Excel 转 JSON 环境是否真的可用我不看单次成功而是跑一组固定用例。准备三张表一张纯文本小表验证基础链路一张带日期和数字的混合表验证类型推断一张带合并单元格和空行的脏表验证容错。三张表都转一遍逐项对照预期结果。第一张表重点看字段名和中文编码输出 JSON 用解析器过一遍确认没有语法错误。第二张表重点看日期列是不是按配置的格式输出、数字列有没有被错误加引号、前导零有没有丢。第三张表重点看空行有没有被跳过、合并单元格填充后的值是否正确、脏数据有没有导致整批失败。三张表都过才算环境稳定。回归验证我一般写成一条命令串起来每次改配置或换版本后重跑# 回归验证三张用例表依次转换并校验 JSON 合法性 cd /d/tools/excel2json/bin for f in basic mixed dirty; do ./excel2json.exe --input ../input/$f.xlsx --output ../output/$f.json --sheet Sheet1 # 用 python 校验 JSON 合法性非法则退出码非零 python -c import json,sys; json.load(open(../output/$f.json,encodingutf-8)) || echo $f 校验失败 done这段脚本里for循环遍历三张用例表每次转换后立刻用 Python 的json.load校验输出文件解析失败会打印表名。|| echo保证单张失败不中断后续方便一次看全所有问题。跑完没有「校验失败」输出说明三张表全部通过。这个习惯是从一次版本升级后日期格式悄悄变了、下游报表全错位那次之后养成的从那以后我每次换 exe 版本或者改 config.ini都强制走一遍这三张表的回归不靠单次手工点击判断。希望这套流程帮到你少在闪退和乱码上耗时间。本文还有配套的精品资源点击获取