后台开放数据文件上传后，运营同事把一份配置导出文件拖进上传框，页面立刻弹出预览失败。开发第一反应往往是前端解析写错了，但实际排查下来，相当一部分问题出在文件本身。JSON预览报错这件事，需要按文件来源、解析环节、展示容错三层依次核对，顺序错了容易在白忙一场之后才找到真正原因。
第一层，核对文件来源与编码
先看文件是怎么来的。从系统导出的JSON、从接口复制粘贴保存的文本、手工编辑过的配置文件，这三类出问题的概率完全不同。重点核对三件事：文件是否带BOM头，编码是否为UTF-8，扩展名和实际内容是否一致。带BOM的JSON在部分解析器中会直接报语法错误，因为BOM被当成了内容的一部分。用文本编辑器另存为无BOM的UTF-8通常就能解决。另外要确认文件不是被改过后缀的，比如实际是HTML错误页或纯文本说明，却被命名为.json，这种文件无论前端怎么写都解析不了。
第二层，核对解析环节
文件没问题，再看解析。常见情况有三类：一是语法错误，多一个逗号、少一个引号、用了单引号，都会让整体解析失败；二是文件体积过大，几十兆的JSON在浏览器里同步解析会卡住甚至超时；三是嵌套层级过深，递归解析时触发调用栈限制。排查时建议做最小化复现：把原文件逐步删减，直到能解析为止，最后剩下的那一段往往就是问题所在。也可以在本地用命令行工具先验证一遍，确认文件本身合法，再回到页面排查，这样能快速区分是文件问题还是代码问题。
第三层，核对展示与容错
解析成功但页面仍不好用，属于展示层的问题。要检查报错提示是否可读，直接抛出解析器的原始异常对用户没有意义，应转换成“文件格式不正确，请检查后重新上传”这类明确指引。还要判断是否所有JSON都适合在线预览，超大文件或结构复杂的数据，降级为提供下载链接往往比强行渲染更稳妥。预览组件本身也要有兜底，解析失败时页面不应整体崩溃。
给一份可执行的核对清单：确认文件编码为无BOM的UTF-8；确认扩展名与实际内容一致；用本地工具验证语法合法性；检查文件体积是否超出预览上限；检查嵌套深度；确认报错提示对用户可读；确认失败时有下载或重试入口。it数运在网站维护中通常会把允许上传的类型与预览能力逐项对齐，不能预览的格式明确提供下载，避免用户上传成功却看不到内容。
JSON预览报错，先确认文件能否被正确解析，再谈页面体验。把解析问题误判成前端故障，改了半天代码，问题可能还在那份文件里。
