前端导出CSV与Excel实战：编码、性能与安全全解析-平芜编程栈

前两年做后台管理系统的时候，几乎每个月都要被“导出”这个需求绊一跤。今天产品说要导出 CSV，明天客户指名要 Excel，后天又有人说“你们导出的文件打开乱码”，大后天又来一个“几十万行数据一导出浏览器就卡死”。前端导出 CSV 和 Excel 这件事，看起来不过是个“把数组变成文件”的小功能，但真正做下来，牵扯到字符编码、文件格式规范、浏览器兼容、大数据量性能、甚至是表格公式注入安全，水比想象中深得多。

这篇文章就把我在实际项目中反复踩过、填平又踩过的几条路梳理一遍：从最轻量的纯前端 CSV 方案，到用 SheetJS/xlsx 生成 Excel，再到用 ExcelJS 做花式样式和合并单元格，最后聊一下大文件导出的取舍思路。写出来的内容尽量偏向实战，附上可直接抄走的代码片段，也把每个方案背后的“为什么”讲清楚，适合正在做后台管理、数据中台或者报表类项目的前端朋友参考。

1. 内容整体设计与思路拆解

1.1 导出功能到底应该谁来干

先聊方案选型。前端导出 CSV 或 Excel，虽然表面上都是“输出一个文件”，但实际工程中通常有三种实现路径，各有各的适用场景，不是一个方案能打天下的。

纯前端本地生成：前端拿到数据后，自己拼字符串或者调用前端库生成文件，通过浏览器下载。优点是省了一次网络请求，后端接口压力小，适合数据量不大（比如万行以内）、数据已经在前端内存里的场景。缺点是一旦数据量上来了，页面会卡，而且如果数据需要联表查询、清洗、脱敏，前端处理逻辑会变得很重。
后端生成文件返回给前端：后端负责造文件，前端只负责拉取并触发下载（或下载后端文件地址）。优点是可以处理千万级数据、可以用服务端内存和 CPU、更方便做权限控制和审计日志，而且文件格式不管多复杂，后端都能用成熟库处理。缺点是前后端需要约定接口格式，文件需要暂存或走流式返回，部署上多一点成本。
混合方案：前端发起导出请求，后端异步把文件生成好放到临时存储（或直接响应文件流），前端用 Blob 接收并保存。这种方案本质上仍是后端生成，只是“下载动作”由前端控制，比较符合前后端分离项目的习惯，也可以配合消息队列做导出任务状态轮询。

我个人在做技术选型时，会先问三个问题：数据量多大？样式要求多高？数据是否需要服务端加工？如果数据就几百行、样式要求不高，那纯前端方案最简单；如果数据量大、需要做复杂列头合并和条件格式，js 库能顶住一部分，但实在太大还是要后端出马。

1.2 选型之前要衡量的四个核心维度

具体到前端存档导出方案，我认为必须围绕四个维度做取舍。

第一，数据量级。纯前端生成 CSV，几十 MB 也扛得住，解析几十万行数据的二维数组再转成字符串，瓶颈主要在内存和 JS 主线程执行时间。生成 xlsx 时如果用了 SheetJS 社区版，对大数据量支持也还行，但遇到几十万行时仍然会有明显耗损。ExcelJS 的生成性能和内存占用要更重一些，超过两万行就开始有点喘。所以数据规模一旦上来，别硬扛，直接考虑后端方案。

第二，样式诉求。CSV 根本不支持样式，Excel 则可以做列宽、单元格合并、字体、边框、条件格式、图表。如果用户要求“导出的 Excel 打开后跟页面上这个报表长得一模一样”，那基本告别 CSV，直接上 ExcelJS，或者后端用 POI 之类的库生成。

第三，代码体积和依赖成本。纯前端写 CSV 不需要任何依赖，一个工具函数就完事。SheetJS 社区版通过 npm 引入目前还是能用的，整体体积相对可控。ExcelJS 功能强但体积大，打包后通常 800KB 以上，需要掂量一下。如果项目对首屏体积敏感，可以考虑按需加载或者动态 import。

第四，兼容性与安全性。CSV 通过 UTF-8 BOM 解决中文 Excel 乱码，但 Mac 的 Numbers 对 CSV 的表现又和 Windows Excel 不完全一样。Excel 文件本身要考虑公式注入，CSV 甚至有“以等号开头的内容被当成公式”的安全隐患。这些坑我在后面专门用一节来写。

1.3 为什么我平时优先选择“前端生成文件 + Blob 下载”

在我接触的一堆中后台项目里，其实大量导出场景都属于“数据量几千行、列头固定、样式要求不高”的类型。这类需求用“前端拿到数据 -> 本地组装文件 -> Blob 转 URL -> 触发浏览器下载”这套链路，效率最高，用户体验也顺滑。

关键原因有这么几点：一是减少一次服务端文件生成与回传的延迟，也不用担心临时文件在服务器上堆积；二是代码直观可测，格式逻辑全在前端，出问题本地就能断点调试；三是很多项目本身接口就会把查询结果返回给前端做列表展示，导出只是把同一份数据换个形态，没必要再让后端跑一遍。当然，如果接口设计是“列表接口只返回当前页”，那前端导出就容易缺数据，这时候要么改接口支持全量返回，要么就走后端导出。

2. 核心细节解析与实操要点

2.1 CSV 并不是“随便拼个逗号文件”

很多人写 CSV 导出，上来就是array.join(',')加\n，然后直接下载。运气好的话，纯英文数字数据没问题，但一遇到包含逗号、换行、双引号的中文字段，文件就错乱了。原因在于 CSV 遵循的是一套约定俗成的文本格式，规范可以参考 RFC 4180，核心规则有三条：

字段内如果包含逗号、双引号、换行符，整个字段应该用双引号包围；
字段内的双引号要写成两个连续双引号进行转义；
行与行之间用\r\n结尾最稳妥，虽然单个\n多数软件也能识别，但 Windows 下的 Excel 对\r\n更友好。

我封装 CSV 导出工具时，会专门写一个escapeCell函数，对每个单元格做一次合法性检查，再决定要不要加引号。否则日期里带个逗号，地址里带个换行，导出来的文件谁打开谁崩溃。

function escapeCell(value) { const str = value === null || value === undefined ? '' : String(value); if (/[",\n\r]/.test(str)) { return '"' + str.replace(/"/g, '""') + '"'; } return str; }

这个函数看着简单，但它是 CSV 方案里最容易忽略又最关键的部分。面试的时候如果问到“前端怎么导出 CSV”，能主动说出转义双引号的人不多，能把 BOM 和逗号转义都讲全的就更少了。

2.2 打开乱码？问题多半出在编码和 BOM

CSV 导出的另一个高频坑是中文乱码。这里必须解释清楚一个现象：浏览器下载的文本文件默认是 UTF-8 编码，但 Windows 版 Excel 在打开 CSV 时，默认会尝试用系统本地编码（中文系统通常是 GBK/ANSI）去解析。UTF-8 编码的中文内容被当成 GBK 去读，自然就变成“锟斤拷”或者乱码。

解决办法是在文件最前面加一个 UTF-8 BOM（字节顺序标记），也就是\uFEFF。Excel 识别到 BOM 后会老老实实按 UTF-8 解码，乱码问题就能解决。这个技巧我在项目中几乎是条件反射级别：只要生成 CSV 送给浏览器下载，第一个字符永远是\uFEFF。

const csvContent = '\uFEFF' + rows.map(row => row.map(escapeCell).join(',')).join('\r\n');

补充一句，Mac 的 Numbers 对 CSV 的分隔符处理比较特殊，有些版本还是按系统区域设置识别分隔符，所以中文环境下导出的逗号分隔 CSV 在 Numbers 里可能出现“一整列挤在一起”的情况。要彻底规避的话，可以改成用制表符\t做分隔符的 TSV，或者直接导出真正的 xlsx 文件，这是很多国际化的 SaaS 产品的做法。

2.3 xlsx 文件不是“简单文本”，它就是压缩包

CSV 是纯文本，Excel 的老版.xls是二进制复合文档，而现代.xlsx文件本质是一个 ZIP 压缩包，里面装着多个 XML 文件，分别描述工作簿结构、单元格数据、样式、共享字符串等。这意味着前端要是想“纯手写”一个 xlsx，等于要自己实现 XML 打包和压缩，几乎不可行。

所以前端生成真正的 xlsx 文件，主流做法是借助现成库。常见有 SheetJS（社区版包名xlsx）和 ExcelJS 两个选择。SheetJS 的优势是轻量、API 简单，几行代码就能把表格数据变成 xlsx；ExcelJS 的强项是丰富的样式能力和细粒度的单元格操作，做复杂报表更顺手。需要补充的是，SheetJS 社区版目前在 npm 上已经停止更新，但这并不影响它在老项目里的稳定表现，新项目如果依赖它的高级企业功能，务必注意 license 问题。

2.4 下载动作的底层原理：Blob、Object URL 与 a 标签

无论导出 CSV、xlsx 还是任何文件，前端触发下载的核心模式是一样的：把文件内容封装成 Blob，用URL.createObjectURL()生成一个临时 URL，挂到<a>标签上并模拟点击，最后释放 URL。

这里面有一个细节值得留意：URL.revokeObjectURL()一定要调用，否则每个下载过的 Blob URL 都会占内存，长时间跑批导出时页面会越来越卡。但也不能创建完 URL 立刻 revoke，要等a.click()执行完之后再释放，最稳妥的做法是监听 click 后延迟释放，或者直接在setTimeout(() => URL.revokeObjectURL(url), 1000)里处理。

function downloadByBlob(blob, filename) { const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = filename; document.body.appendChild(a); a.click(); document.body.removeChild(a); setTimeout(() => URL.revokeObjectURL(url), 1000); }

需要注意的是，a.download这个属性在跨域地址下会失效，也就是说如果用外链地址下载文件，浏览器可能会直接跳到文件而不是下载。但 Blob URL 是同源的，所以这个模式基本不会遇到问题。另外在 Safari 里，老版本对a.download的支持不太好，需要额外处理，我放到后面问题排查里展开。

3. 实操过程与核心环节实现

3.1 最轻量方案：纯手写 CSV 导出工具函数

这是我最喜欢的方案，没有依赖、逻辑透明、测试也方便。使用场景是：数据量小、列头固定、样式无要求、只想快速落一个“导出表格”按钮。

第一步，定义列配置。我会约定一个数组，每个元素包含key和title，这样后端返回字段名和表头不一致时也能灵活映射。

const columns = [ { key: 'name', title: '姓名' }, { key: 'phone', title: '联系电话' }, { key: 'address', title: '地址' }, ];

第二步，把行数据转换成二维数组，再用escapeCell和\r\n拼接成 CSV 字符串。这一步为了性能，我会直接用数组收集每一行，最后join，尽量避免在循环里做字符串+=，数据量大时差异明显。

function exportCSV(columns, list, filename = 'export.csv') { const header = columns.map(col => escapeCell(col.title)); const rows = list.map(item => columns.map(col => escapeCell(item[col.key]))); const csv = '\uFEFF' + [header, ...rows].map(line => line.join(',')).join('\r\n'); const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' }); downloadByBlob(blob, filename); }

第三步，触发下载。注意文件名如果包含中文，a.download直接设置中文名在现代浏览器里没问题，但为了跨浏览器兼容，可以给文件名做一次 URL 编码兜底处理。

这里有一个我实际踩过的坑：如果数据里有数字字符串超过 15 位，比如身份证号、订单号，CSV 导出后 Excel 打开会自动转成科学计数法。应对方式有两种，一是导出前在数据前面加一个制表符（\t）强行告诉 Excel“这是文本”，二是导成 xlsx 时把单元格类型写成字符串。前者对 CSV 有效且简单，但有副作用，某些数据库或工具导入 CSV 时会把\t也带进去，需要看具体场景取舍。

3.2 使用 SheetJS（xlsx）导出 Excel 文件

当需求从“导出 CSV”变成“导出 Excel”，而且用户明确说“我要 xlsx 后缀”，我最常用的就是 SheetJS 社区版。

安装依赖：

npm install xlsx

然后核心代码其实很短，关键是理解四个 API：aoa_to_sheet（二维数组转工作表）、json_to_sheet（对象数组转工作表）、book_new（创建新工作簿）、writeFile（生成并下载文件）。

import XLSX from 'xlsx'; function exportExcelByXLSX(columns, list, filename = 'export.xlsx') { const header = columns.map(col => col.title); const rows = list.map(item => columns.map(col => item[col.key])); const sheetData = [header, ...rows]; const worksheet = XLSX.utils.aoa_to_sheet(sheetData); const workbook = XLSX.utils.book_new(); XLSX.utils.book_append_sheet(workbook, worksheet, 'Sheet1'); XLSX.writeFile(workbook, filename); }

这段代码可以满足 90% 的简单 Excel 导出需求。需要注意几点：第一，writeFile内部已经做了 Blob 和下载，不需要再自己实现downloadByBlob；第二，列宽是可以设置的，但社区版设置列宽需要手动操作worksheet['!cols']，不然导出的 Excel 列宽完全不自适应，打开后所有列都挤在一起：

worksheet['!cols'] = columns.map(col => ({ wch: col.width || 20 }));

第三，如果数据是直接从接口拿到的对象数组，用json_to_sheet更省事，但它的列顺序取决于对象 key 的插入顺序，如果需要指定顺序，还是老老实实先map成二维数组再传aoa_to_sheet更可控。

3.3 用 ExcelJS 做合并单元格、列宽和样式

如果需要导出的 Excel 长得很“报表”，比如第一行是标题、第二行是导出日期、第三行才是表头，还要合并单元格、设置背景色和边框，那 SheetJS 社区版用起来就比较拧巴，这时候我建议直接上 ExcelJS。

ExcelJS 的常规用法是：创建工作簿 -> 创建工作表 -> 逐行写入单元格 -> 操作样式 -> 生成 ArrayBuffer -> 通过 Blob 下载。

import ExcelJS from 'exceljs'; async function exportExcelByExcelJS(columns, list, filename = 'report.xlsx') { const workbook = new ExcelJS.Workbook(); workbook.creator = '前端导出服务'; const sheet = workbook.addWorksheet('报表', { views: [{ state: 'frozen', ySplit: 2 }], }); // 标题行，合并 A1 到最后一个列 sheet.mergeCells(1, 1, 1, columns.length); const titleCell = sheet.getCell(1, 1); titleCell.value = '2025年度数据报表'; titleCell.font = { size: 16, bold: true }; titleCell.alignment = { vertical: 'middle', horizontal: 'center' }; // 列头行 const headerRow = sheet.getRow(2); columns.forEach((col, index) => { const cell = headerRow.getCell(index + 1); cell.value = col.title; cell.font = { bold: true }; cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFE2EFDA' } }; cell.border = { bottom: { style: 'thin', color: { argb: 'FF999999' } } }; }); // 数据行 list.forEach((item, rowIndex) => { const row = sheet.getRow(rowIndex + 3); columns.forEach((col, colIndex) => { row.getCell(colIndex + 1).value = item[col.key]; }); }); // 列宽 columns.forEach((col, index) => { sheet.getColumn(index + 1).width = col.width || 18; }); // 生成文件 const buffer = await workbook.xlsx.writeBuffer(); const blob = new Blob([buffer], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', }); downloadByBlob(blob, filename); }

ExcelJS 的学习曲线比 SheetJS 陡一些，但它的 API 设计更贴近 Excel 对象模型，什么getCell、mergeCells、getRow、getColumn都很直观。还有一个很实用的功能是冻结窗格，我在导出长报表时一般会设置views: [{ state: 'frozen', ySplit: 2 }]，这样用户下拉几千行时也能看到标题和表头。另外一个坑是writeBuffer()返回的是ArrayBuffer还是Buffer取决于环境，浏览器端一般拿到ArrayBuffer，直接用Blob([buffer])没问题，但如果是在 Node 环境做 SSR，就得注意转成Buffer才不会出错。

3.4 大文件导出、分片处理与性能优化

前端导出最怕“大”。几千行没事，几万行开始有卡顿，几十万行可能直接把页面搞死。如果需求真的到了大文件导出那一步，我的建议顺序是这样的。

先看能不能转后端：只要数据量超过五万行，或者后端接口返回的数据本身就很大，优先考虑让后端生成文件，前端通过 Blob 接收下载。后端可以用流式写出，一边查数据库一边写文件，内存压力小得多，还能配合定时任务提前生成报表压缩包。

如果条件限制必须前端处理大数据量，有几个缓解手段。一是分批写入，比如把 20 万行数据切成每批 5000 行，用setTimeout或者requestIdleCallback分片处理，避免主线程长时间阻塞导致页面卡死：

function exportLargeCSV(columns, list, filename, batchSize = 5000) { const total = list.length; let cursor = 0; const chunkRows = []; function processBatch() { const end = Math.min(cursor + batchSize, total); for (let i = cursor; i < end; i++) { chunkRows.push(columns.map(col => escapeCell(list[i][col.key])).join(',')); } cursor = end; if (cursor < total) { setTimeout(processBatch, 0); } else { const csv = '\uFEFF' + [columns.map(col => escapeCell(col.title)).join(',')].concat(chunkRows).join('\r\n'); const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' }); downloadByBlob(blob, filename); } } processBatch(); }

二是用 Web Worker 做字符串拼接，把耗时计算丢到后台线程，UI 就不会卡了。但这种方案比较麻烦，Worker 里拿不到 DOM，只能把纯计算放进去，最后把结果 postMessage 回来再下载，适合对体验要求高的场景。

三是控制导出按钮的“点击后防抖”，防止用户重复点击生成多个任务。我在项目里的做法是：点击导出后立刻将按钮置灰，等文件触发下载后再恢复，同时在文案上提示“正在生成文件，数据量较大请稍候”。

3.5 配合后端接口下载文件的常见写法

最后补一个与后端配合的下载方案。很多后端导出的接口，返回的是二进制流而不是 JSON，前端如果直接用 axios，需要设置responseType: 'blob'。

async function downloadFromBackend(url, params, filename) { const response = await axios.post(url, params, { responseType: 'blob', }); const blob = new Blob([response.data]); downloadByBlob(blob, filename); }

这种方法经常遇到的一个坑是：后端返回文件流时同时在响应头里带了Content-Disposition，里面可能有文件名，但前端用 axios 默认拿不到这个头，需要在后端开启Access-Control-Expose-Headers。所以前后端要约定好文件名是前端写死还是从接口字段里返回，否则下载出来的文件就是乱码文件名。

另外后端在生成文件失败时会返回 JSON 错误信息，但由于设置了responseType: 'blob'，前端拿到的 response.data 是一个 Blob，直接response.data.message会拿不到。需要先把 Blob 转成文本再解析 JSON：

if (response.data.type === 'application/json') { const text = await response.data.text(); const errorData = JSON.parse(text); alert(errorData.message || '导出失败'); return; }

这个分支判断我想特别强调一下，因为很多新人在第一次接后端导出接口时都会在这里卡住，明明后端返回了错误提示，前端却弹不出来，最后只能靠猜。

4. 常见问题与排查技巧实录

4.1 CSV 导出打开中文乱码

这个问题前面已经给了标准答案，就是拼\uFEFFBOM。但我在踩坑过程中发现，有时候加了 BOM 还是乱码，多半是文件内容在传输过程中被二次编码了。比如后端接口返回的是字符串，前端再拼 BOM，如果中间经过了decodeURIComponent或者TextDecoder，BOM 可能被吃掉。排查时就三步：先看 Content-Type 是否包含charset=utf-8；再确认字符串在生成 Blob 前是否是正常中文；最后用文本编辑器打开文件，用十六进制模式看文件头三个字节是不是EF BB BF，不是的话补 BOM。

4.2 Excel 报“文件格式和扩展名不匹配”

这个报错的常见原因是“文件内容不是真正的 xlsx，但文件名后缀是 xlsx”。最典型的情况是后端接口返回的是 HTML 报表，但前端硬要存成.xls或者.xlsx；或者 SheetJS 生成的其实是旧版的biff格式，却用了新扩展名。排查思路是先把下载的文件用文本编辑器打开，看看开头有没有PK（ZIP 文件头），没有的话说明文件格式不对。如果确实需要 HTML 形式的 xls（有些人会这么干），后缀应该存成.xls，并且要补上 HTML 的 MIME 类型，这样老版本 Excel 能打开。

4.3 长数字变成科学计数法、精度丢失

Excel 里超过 11 位的数字会自动变成科学计数法，超过 15 位会因为浮点数精度丢失变成尾数一堆 0。处理时要把这类字段明确设置为文本格式。用 SheetJS 时，可以在单元格对象里设置t: 's'，或者直接把值写成字符串；用 ExcelJS 时，可以在getCell后显式设置cell.value为字符串，并在列定义里注明numFmt: '@'，这样 Excel 会按文本来渲染。

// ExcelJS 示例：强制文本格式 const cell = row.getCell(1); cell.value = '12345678901234567890'; cell.numFmt = '@';

4.4 导出的大数据量在浏览器里卡顿或白屏

涉及大数据量时，建议不要把所有数据一次性塞进表格里再导出。可以先从接口分批拉数据，或者直接让后端出文件。如果数据已经在前端内存中，用分片setTimeout+ 分批写入的方式可以缓解卡顿，但不要指望体验能比肩后端流式导出。我个人的阈值是两万行左右，超过这个数直接转后端方案，别在前端折腾。

4.5 某些浏览器点击下载没反应（Safari 特殊处理）

Safari 对a.download的支持历史比较坑，部分版本会把 Blob URL 强制在浏览器新窗口打开而不是下载。兜底方案是：检测到 Safari 时，用window.open(url)或者window.location.href = url作为 fallback。另外 Safari 对通过document.body.removeChild(a)后马上 revoke URL 非常敏感，我建议在 Safari 下保留 URL 不主动 revoke，或者延迟更久再 revoke，否则会出现“第一次能下载，第二次点击没反应”的奇怪现象。

4.6 CSV 公式注入（CSV Injection）

这个安全问题必须单独提出来。如果 CSV 单元格内容以=、+、-、@开头，Excel 打开后会把它当成公式执行，恶意构造的单元格内容可能读取用户本地文件或者做网络请求。虽然现代 Office 会给出安全警告，但作为开发者还是要主动防护。简单做法是：对这类开头字符做转义，在值前面加一个单引号'或者空格，逗号、引号按原样转义分开处理。

function sanitizeCell(value) { let str = value === null || value === undefined ? '' : String(value); if (/^[=+\-@]/.test(str)) { str = "'" + str; } return escapeCell(str); }

这句话值得在高亮里再写一遍：任何允许用户输入数据并导出成表格文件的系统，都要做公式注入过滤，这是在生产环境里真正可能造成安全事件的问题。

4.7 文件名后缀和 MIME 类型匹配

下载文件时，a.download的后缀名和 Blob 的type必须尽量匹配。CSV 用text/csv;charset=utf-8;，xlsx 用application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，不然某些浏览器会把文件当成二进制下载，或者干脆拒绝。xls 老格式的 MIME 类型是application/vnd.ms-excel，注意别和 xlsx 混用。

5. 工具选型速查和经验总结

这部分我用表格做一个方案速查，方便大家在做技术方案评审时直接套用。

方案	依赖	样式能力	大数据量	适用场景
手写 CSV + Blob	无	无	中	简单列表导出、内部系统快速导出
SheetJS / xlsx	需引入库	基础列宽、简单合并	中	标准 xlsx 导出，通用性最好
ExcelJS	需引入库	丰富样式、合并、图片、图表	中低	复杂报表、需要样式的业务表单
后端生成 + 前端下载	后端决定	取决于后端	高	大数据量、需要服务端权限控制