夜雨聆风学习资料网

ARTICLE · 1366866

Vue3 导入导出 Excel 进阶:流式解析与错误行回写

Vue3 导入导出 Excel 进阶:流式解析与错误行回写
基础导入导出那套链路解决的是「能不能读进来、能不能导出去」:模板怎么下、字段怎么校验、错误行怎么在页面上标出来、当前页还是全量导出。文件一大就露馅——一个几万行的 xlsx 选完,页面卡住不动,等解析完又只给一句「某行有误」,人还得自己回去翻原表。这篇整理的是把导入链路往大文件推一步的设计:解析搬进 Worker、按行分帧回传、错误行不再只做页面回显,而是回写成一份带标注的 xlsx,下载改完直接再传。文中代码是可直接搬进工程的骨架,按库的接口契约写全;这一篇不配 demo,也没有实拍数据和性能数字,凡涉及库能力与限制处一律按官方文档口径说明。

范围:补的是哪一段

先把不做的划掉:模板下载、字段预校验、页面内错误行回显、CSV 与 xlsx 的导出语义、长数字与日期的格式坑,这些基础链路里已经覆盖,这里不重复。这一节只解决三件事:大文件读的时候页面不卡、进度能看见、错误能带走。

三件事对应三个技术判断,顺序不能换。第一个判断是「文件能不能切开」,它决定了后面所有分批方案的形态;第二个判断是「浏览器端到底有没有流式」,它决定了该选哪个能力面;第三个判断是「错误交给谁」,它决定了回写文件的结构。下面按这个顺序展开。

整条链路的分工:只有 Worker 做解析,主线程负责交互与交付

先看清 xlsx 是什么:按字节切片不成立

「文件大就切块」是第一个容易走岔的念头。File.prototype.slice() 确实能按字节切出 Blob,但 xlsx 是一个 ZIP 容器:内部是压缩过的一组 XML,而记录「有哪些文件、各自在哪」的中央目录写在文件尾部。按字节切出来的任何一段都不是合法 ZIP,解压器连入口都找不到,更谈不上解析出某一批行。

所以这里的「分批」要换个定义:整份读入、分批产出。读入是一次性的,分的是解析结果回传的节奏,不是文件的字节。这一条决定了后面 Worker 里只能有一个完整 ArrayBuffer,也决定了「流式」这个词在这篇里的准确含义——不是字面意义上的流式 IO,而是「解析不占主线程」加「产出按帧回传」两件事的组合。

别把「边读边解析」当成浏览器端能力写进设计文档。ZIP 的中央目录在尾部,拿不到完整文件就无法列出内部条目,这是容器格式决定的,换哪个解析库都一样。

浏览器端到底有没有流式:按官方口径对齐

三个常被混为一谈的能力面,先分开:ExcelJS 的 streaming、SheetJS 的读取选项、以及「交给服务端」这条退路。

路线
浏览器端实际可用
结论
ExcelJS
workbook.xlsx.load(buffer)
 与 workbook.xlsx.writeBuffer() 可用;ExcelJS.stream.xlsx.WorkbookReader / WorkbookWriter 是面向 Node 流的 API,官方说明浏览器构建不包含 streaming reader 与 writer
别在浏览器里找 streaming reader,回写文件用 writeBuffer()
SheetJS 社区版
XLSX.read(data, opts)
 支持 dense、sheetRows、cellStyles: false、cellFormula: false 等选项;官方对超过 10 万行的工作表建议启用 dense 模式,在新版浏览器里更省内存
是省内存的整读,官方没有把它定义为真正的流式解析
服务端解析
SheetJS 官方文档对超大文件的建议是放到服务端处理;浏览器侧受限于内存、ZIP 解压与机型差异
超过目标机型的承受范围就该换路线,阈值按实测定

结论不复杂:浏览器侧要的不是「流式解析」这个名头,而是把整读的代价从主线程挪走、把内存压到能接受的范围。dense: true 值得单独说一句——它让单元格以二维数组存放,取值方式从稀疏模式的 ws['B2'] 变成 ws['!data'][R][C](行列都是零基),遍历前还要先判 ws['!data'] 是否存在。这是官方给的迁移写法,也是照着旧示例抄最容易错的一处。

凡是把 dense 与 sheetRows 说成「流式读取」的说法都别采信。它们改变的是解析用量与结果规模,文件仍然要完整地进内存一次。

把解析搬进 Worker:转移所有权而不是复制

Web Worker 是独立于主线程的 JS 执行环境,解析这种同步重活放进去,主线程就不会被长任务卡住。Vite 下用 new URL('../workers/excel.worker.js', import.meta.url) 配 { type: 'module' } 创建,构建时会把 Worker 单独打成一个 chunk。

关键在 postMessage 的第二个参数。默认情况下消息走结构化克隆,一个几十 MB 的 ArrayBuffer 会被完整复制一份,内存里同时存在两份;把它列进可转移对象(transferable)清单后,交出去的是所有权,零拷贝——不产生第二份数据,转移完成后主线程上这个 buffer 变为不可用状态,别再拿它做别的。

// src/composables/useExcelImport.jsexport function createWorker() {  return new Worker(    new URL('../workers/excel.worker.js', import.meta.url),    { type: 'module' }  )}let worker = createWorker()let running = falseexport function onWorkerMessage(handlers) {  worker.onmessage = (e) => {    const { type, payload } = e.data    if (type === 'batch') handlers.onBatch(payload.rows)    if (type === 'progress') handlers.onProgress(payload.done, payload.total)    if (type === 'done') handlers.onDone(payload)  }}export async function parseFile(file) {  const buffer = await file.arrayBuffer()       // 整份读入,不切片  worker.postMessage(    { type: 'parse', buffer, batchSize: 500 },    [buffer]                                    // transferable,零拷贝转交所有权  )  // 转移之后主线程上的 buffer 已不可读,别再复用它}

消息协议先定死三类:batch 带一批有效行、progress 带已完成与总数、done 带错误行集合并标记结束。协议简单一点,后面取消与重建 Worker 时心智负担小很多。

分批产出:按行分帧,进度与数据分两条消息

分帧指每攒够 N 条有效行发一次 batch,而不是每解析一行就发一条消息。消息太密,跨线程通信本身会变成新瓶颈;N 取 500 起步,按目标机型的实际耗时调。进度单独发,这样界面可以只更新一个数字,不必把整批行数据绑在进度上。

// src/workers/excel.worker.jsimport * as XLSX from 'xlsx'import { SCHEMA, validateRow, collectErrors } from '../lib/validate.js'function pickRow(ws, r, range) {  const data = ws['!data']                    // dense 模式:ws['!data'][r][c]  const line = data ? (data[r] || []) : []  const out = []  for (let c = range.s.c; c <= range.e.c; c++) {    const cell = line[c]    out.push(cell ? cell.v : null)  }  return out}self.onmessage = (e) => {  const { buffer, batchSize = 500 } = e.data  const wb = XLSX.read(new Uint8Array(buffer), {    type: 'array',    dense: true,            // 单元格存进 ws['!data'] 二维数组    cellStyles: false,      // 不解析样式    cellFormula: false      // 不保留公式文本  })  const ws = wb.Sheets[wb.SheetNames[0]]  const range = XLSX.utils.decode_range(ws['!ref'] || 'A1')  const total = range.e.r - range.s.r          // 去掉表头后的数据行数  const allErrors = []  let rows = []  let done = 0  for (let r = range.s.r + 1; r <= range.e.r; r++) {   // +1 跳过表头    const values = pickRow(ws, r, range)    const errs = validateRow(values, SCHEMA, r + 1)     // 传 1 基行号    allErrors.push(...errs)    if (errs.length === 0) rows.push(values)            // 只把通过的行放进批次    done++    if (rows.length >= batchSize) {      self.postMessage({ type: 'batch', payload: { rows } })      rows = []    }    if (done % batchSize === 0) {      self.postMessage({ type: 'progress', payload: { done, total } })    }  }  if (rows.length) self.postMessage({ type: 'batch', payload: { rows } })  self.postMessage({ type: 'done', payload: collectErrors(allErrors) })}

这段骨架只取第一个工作表,从第二行起遍历以跳过表头;校验在 Worker 内完成,只有全列通过的行才进 batch,错误行进 allErrors。校验规则要放在 Worker 能直接 import 的模块里,别通过 postMessage 传——结构化克隆不接受函数,带 test 函数的规则对象会直接抛出克隆错误,这是把校验搬进 Worker 时第一个会撞上的坑。

pickRow 返回的是原始值数组,长数字与日期的格式问题在基础链路里已经处理过,这里沿用同一套规范化函数,不要在 Worker 里再写一份。进度按 done 的整数倍发,与批次解耦:错误多的文件里有效行攒得慢,进度不该跟着停住。

校验:错误行的数据契约

错误行的数据契约要瘦。把整行原始数据塞进错误对象,几万行里错几千行就等于又复制了一份表;固定只留定位字段、原因,外加出错单元格的原始值——用户对照时唯一需要看到的就是这个值,别把整行搬过来。行号列号用 1 基,和用户对着 Excel 看到的一致,别让人做减一换算。

// src/lib/validate.jsexport const SCHEMA = [  { label: '姓名', required: true },  { label: '手机号', required: true, test: (v) => /^\d{11}$/.test(String(v)) }]function makeError(row, col, code, message, raw) {  return { row, col, code, message, raw }   // 行号列号 1 基,与 Excel 一致}export function validateRow(values, schema, lineNo) {  const errors = []  schema.forEach((rule, i) => {    const v = values[i]    if (rule.required && (v === null || v === '')) {      errors.push(makeError(lineNo, i + 1, 'REQUIRED', `${rule.label} 不能为空`, v))    }    if (v !== null && rule.test && !rule.test(v)) {      errors.push(makeError(lineNo, i + 1, 'FORMAT', `${rule.label} 格式不对`, v))    }  })  return errors}export function collectErrors(all, limit = 500) {  // 错误数据本身也可能撑爆内存,超出上限只记总数  if (all.length <= limit) return { errors: all, truncated: false, total: all.length }  return { errors: all.slice(0, limit), truncated: true, total: all.length }}

truncated 这一个布尔值必须往上传,否则用户会以为下载的文件里就是全部错误。它属于「不静默丢数据」的基本约束,比多存几百行重要。

错误行回写:生成一份带标注的 xlsx

页面内回显表格适合错误少的时候,一眼能看完;错误行成千上万条,页面表格既翻不动也带不走。回写文件是另一种交付:把错误行连同原因写成新工作簿,用户下载、在原文件里改、再上传,形成闭环,不需要在页面上抄行号。

分批产出与错误回写:一个 buffer 进来,有效行与错误文件两条结果下去

浏览器端 ExcelJS 用 writeBuffer() 生成文件内容,配 cell.fill 给错误原因上底色,再走 Blob 加临时 URL 触发下载。这里的 cell.fill 是样式写入,和前面「解析时不读样式」不冲突:读入侧省掉的是对源文件的样式解析,写出侧是自己新建工作簿时设的填充。

// src/lib/writeErrorFile.jsimport ExcelJS from 'exceljs'export async function writeErrorFile(errors, fileName = '错误行.xlsx') {  const wb = new ExcelJS.Workbook()  const ws = wb.addWorksheet('错误数据')  ws.addRow(['原行号', '列号', '错误码', '错误原因', '原始内容'])  errors.forEach((err) => {    ws.addRow([      err.row,      err.col,      err.code,      err.message,      String(err.raw ?? '')                // 原值随错误行一起带过来    ])  })  const red = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFFFC7CE' } }  ws.eachRow((row, rowNumber) => {    if (rowNumber === 1) return    row.getCell(4).fill = red            // 错误原因列标红  })  ws.getColumn(1).width = 12  ws.getColumn(4).width = 40  ws.getColumn(5).width = 30  const buf = await wb.xlsx.writeBuffer()   // 浏览器端可用;非 streaming  const url = URL.createObjectURL(new Blob([buf], {    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'  }))  const a = document.createElement('a')  a.href = url  a.download = fileName  a.click()  URL.revokeObjectURL(url)}

「原始内容」这一列别省。用户拿到文件时要对照自己填了什么,只有行号和一句「格式不对」还得切回原表,闭环就断了。取值用错误对象自带的 raw,不要拿 err.row 去页面表格里回查——页面里存的是过滤后的有效行,行号早就对不上了。

取消、并发与内存:四条提前定好的规则

Worker 没有「中断当前同步任务」的 API,解析一旦开始,唯一可靠的取消是 terminate(),然后重建实例。重建这一步不能省:旧实例如果还挂着消息回调,状态会被残留消息污染。

// 取消 = 终止后重建,同时清掉已收的批次、进度与错误集合export function cancelImport(resetState) {  worker.terminate()  worker = createWorker()  resetState()  running = false}// 同一时刻只允许一个导入在跑,避免两次 postMessage 的消息互相串export async function start(file, handlers) {  if (running) return  running = true  onWorkerMessage({    onBatch: handlers.onBatch,    onProgress: handlers.onProgress,    onDone(payload) {      running = false               // 解析真的结束才解锁      handlers.onDone(payload)    }  })  try {    await parseFile(file)           // 只是投递消息,很快返回  } catch (e) {    running = false    throw e  }}

这里的锁最容易写错成「await parseFile(file) 之后就解锁」。postMessage 是异步投递,消息发出去不等于解析结束,锁必须在收到 done 时才放开,否则连选两次文件,两批 batch 消息会混进同一张表。

另外两条规则写在这里,实现时容易漏:buffer 转移后不可复用,取消后要重来就得重新 file.arrayBuffer();错误集合要限流,并回传 truncated。至于「多大的文件该改走服务端」,不给一个凭空写下的数字——按目标机型的实测内存与耗时定阈值,浏览器侧至少要把「内存里同时存在完整 buffer 与解析结果」这个事实算进去。

串起来:把界面层做薄

组件层薄一点更好维护:选文件、收批次、更新进度、触发错误文件下载,外加一个取消入口。解析、校验、回写都在各自的模块里,界面不碰 ArrayBuffer,也不碰 ZIP。

<script setup>import { ref } from 'vue'import { start, cancelImport } from './useExcelImport'import { writeErrorFile } from './writeErrorFile'const rows = ref([])const errors = ref([])const progress = ref({ done: 0, total: 0 })const truncated = ref(false)const handlers = {  onBatch(list) { rows.value.push(...list) },  onProgress(done, total) { progress.value = { done, total } },  onDone(payload) {    errors.value = payload.errors    truncated.value = payload.truncated  }}async function onFileChange(e) {  const file = e.target.files?.[0]  if (!file) return  rows.value = []  errors.value = []  await start(file, handlers)}function onDownload() {  const name = truncated.value ? '错误行(前500条).xlsx' : '错误行.xlsx'  return writeErrorFile(errors.value, name)}function onCancel() {  cancelImport(() => {    rows.value = []    errors.value = []    progress.value = { done: 0, total: 0 }  })}</script>

下载入口就是按钮绑 onDownload,挂在 done 之后,别在回调里自动弹下载:用户可能想先在页面里看一眼错误分布,自动下载会打断这个动作。被截断时文件名直接写明「前 500 条」,比在页面角落加一行小字更不容易被忽略。

收尾:能力边界与适用条件

把没做的列清楚,比补一段乐观的总结有用。以下均不在这套骨架范围内:

没做
代价与去向
按字节切块并行解析
xlsx 是 ZIP,切出来的片段不是合法容器;要做只能改走服务端分片
真正的流式 IO
浏览器侧仍需整份 ArrayBuffer 进内存,这里的「流式」只指不占主线程加分帧回传
多工作表合并、公式求值、合并单元格、样式还原
读入侧明确跳过样式与公式,取的是单元格原始值
xls 老格式、加密工作簿、断点续传
属于另外的解析路径,不在这条链路上叠
移动端超大文件保障
内存与解压能力差异大,需要按机型实测,不能凭经验给承诺
性能数字与实拍截图
这一篇不配 demo,没有实测数据,代码是按库接口契约写出的骨架

回头看,这套设计真正解决的只有两件事:把整读的代价挪出主线程,把错误从「页面上的一行提示」变成「能带走的一份文件」。前者靠 Worker 与所有权转移,后者靠错误行的数据契约与回写。至于文件大到浏览器扛不住,判断依据应该来自实测,而不是给「大」字配一个想当然的数字。

· · ·

觉得有用的话,点赞、分享、推荐三连支持一下。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料