从一份 CSV 看清数据边界：浏览器本地预检工具的实现与验证

处理一份 CSV 之前，我往往先想知道三件事：有多少条记录、每列缺了多少值、格式有没有在导入时悄悄错位。为了做一次可复现的验证，我写了一个不依赖后端的浏览器小工具「CSV 透镜」：粘贴或选择本地 CSV，解析后展示字段概览和前 100 行预览。这里记录的是实际实现、测试和限制，而不是泛泛的 CSV 教程。

先界定数据格式

本工具只接受 UTF-8、逗号分隔的 CSV，第一行是非空列名。文件上限 1 MiB，数据最多 5,000 条；预览只展示前 100 条，但空值与去重统计覆盖所有已解析记录。这个边界是有意设置的：浏览器端工具适合快速预检，不应暗示可以直接处理任意体量的数据。上传控件通过浏览器 File API 读取文件，页面服务端只提供静态资源，没有文件接收接口。

为什么不能直接 split(‘,’)

例如下面这段内容：

姓名,备注
林,"包含,逗号"
周,"第一行
第二行"
何,"双引号""示例"

第二行的逗号是字段内容；周这一条记录的换行也仍在同一个字段里；连续两个双引号表示一个字面引号。若先按行分割，再按逗号分割，会把记录和列数同时弄错。我使用一个逐字符状态机：引号内保留分隔符与换行，遇到成对引号写入一个引号，关闭引号后只允许逗号或行尾。解析结束后逐条检查列数是否与表头相同；错误输入显示具体原因，而不是输出一张看似正常的错表。

统计口径要讲清楚

“空值”定义为字段去掉首尾空白后为空；“不重复值”排除空值，按原始文本精确比较。因此 北京 与 北京 被视为两个不同值，12 与 012 也不会自动合并。它不是数据库中的 NULL 识别器，更不会代替清洗规则。总览展示记录数、字段数和空值总数；每个字段显示自己的空值数和不重复值数。

表格单元格通过 DOM 的 textContent 填入，不把 CSV 内容拼入 innerHTML。这样即使输入包含 HTML 标签，也只会作为文本预览，不会当成页面元素执行。文件在当前浏览器会话中处理，不做自动持久化；仍不建议把它当作敏感信息安全审计器。

实际验证

在 Node.js 24 环境执行 npm test，六组测试全部通过，覆盖基础表格、UTF-8 BOM、CRLF、引号转义、引号内换行、空值与去重统计、格式错误和 1 MiB 限制。浏览器中点击“填入示例”后得到 4 条记录、3 个字段、1 个空值，城市字段显示 1 个空值和 2 个不重复值；输入列数不一致的内容时，预览被清空并显示错误。这个行为比保留上一次成功结果更不容易误导使用者。

运行方法：从公开源码仓库 https://gitcode.com/ccccccjh/csv-local-inspector 克隆项目；Node.js 18+，在项目目录运行 npm test 和 npm run dev，打开本地 4179 端口。这个小工具没有声称支持自动编码识别、海量数据流式处理或数据清洗；这些是明确没有实现的功能。

本文根据本人在 2026 年 10 月 21 日实际开发和验证的代码整理，AI 辅助实现与文字组织。源码和测试已推送到公开 GitCode 仓库；作品馆投稿尚未完成，不把仓库地址当作在线演示地址。