Vue导出Excel手写实现：3个坑让新手代码跑不通的自救指南
Vue导出Excel手写实现：3个坑让新手代码跑不通的自救指南
复制来的Vue导出Excel代码，一跑就报错？别急着怀疑自己手残。
我见过太多开发者，复制完代码直接贴进项目，结果页面白屏或者文件打不开，却不知道怎么调。
其实问题不在你，而在那些“通用模板”没考虑你的具体业务场景。
今天不整虚的，我们手写实现一个真正可控、可维护的Vue导出Excel方案。
不依赖复杂第三方库的魔法封装，从底层原理讲透，让你知道每一行代码在干嘛。
项目目标：告别“复制粘贴”的黑盒思维
很多初学者喜欢用 xlsx 或 file-saver 库，这没错，但黑盒思维是大忌。
一旦项目出现特殊需求，比如合并单元格、特定样式、大数据量分片，黑盒库就束手无策了。
我们要达到的目标是：轻量级：不引入超过 50KB 的依赖。
可视化调试：每一步都能通过控制台看到数据变化。
高度定制：能处理表头映射、数据格式化、空值处理。
兼容性：覆盖 Chrome、Firefox、Safari 主流浏览器。这不是为了炫技，而是为了在生产环境中，当用户投诉“导出的表格格式乱了”时，你能在 10 分钟内定位问题，而不是去翻文档求援。
目录结构：小而美的模块化设计
为了便于理解，我们将代码拆分为三个核心模块，而不是塞进一个巨大的 utils.js 里。
src/
├── utils/
│ ├── excelGenerator.js # 核心生成逻辑
│ ├── dataFormatter.js # 数据预处理与格式化
│ └── fileSaver.js # 文件保存封装
├── components/
│ └── ExportButton.vue # 导出按钮组件
└── main.js # 入口文件这种结构的好处是，数据格式化和文件生成解耦。
你可以单独测试数据是否处理正确，而不需要每次都真的下载一个文件。
这也是工程化思维的基本体现：关注点分离。
核心代码实现：手写实现的底层逻辑
1. 数据预处理：从数组到二维表格
Excel 的本质是一个二维数组。而我们的 Vue 数据通常是对象数组。
这一步是新手最容易踩坑的地方。
很多人直接 JSON.stringify 数据，结果 Excel 里出来的是乱码或者只有一列。
// dataFormatter.js
export function formatData(list, columns) {// 1. 提取表头const headers = columns.map(col = col.label);// 2. 提取数据行const rows = list.map(item = {return columns.map(col = {// 处理空值，避免 undefined 导致 Excel 显示异常let value = item[col.key];// 特殊处理：日期格式化if (col.type === 'date' value) {value = new Date(value).toLocaleDateString('zh-CN');}// 特殊处理：数字精度if (col.type === 'number' value !== null value !== undefined) {value = Number(value).toFixed(2);}return value === undefined || value === null ? '' : value;});});return [headers, ...rows];
}关键细节：col.type 字段让我们在组件中就能定义格式，而不是在导出逻辑里硬编码。
空值处理必须显式返回空字符串，否则 Excel 可能会识别为文本 undefined。2. 生成 Excel 文件：不用库，用 Blob
这是本文的核心。我们不引入 xlsx 库，而是利用浏览器的 Blob API 和 HTML 表格 技巧。
为什么？因为 xlsx 库体积大，且对于简单的表格导出，性能开销反而比直接操作 DOM 高。
原理简述：
Excel 文件本质是 XML 或 CSV 格式。对于简单表格，我们可以生成一个带有特定 MIME 类型的 HTML 表格字符串，浏览器会将其识别为可下载的 Excel 文件。
虽然这不是标准的 .xlsx 格式，但在大多数业务场景下（如数据导出、报表），它完全够用，且兼容性极好。
注：根据 MDN Web Docs 文档，Blob 对象代表一个不可变的、类似文件的对象，它可以在内存中存储数据。
// excelGenerator.js
import { formatData } from './dataFormatter';
import { saveAs } from './fileSaver';export function generateExcel({ data, columns, fileName = 'export' }) {// 1. 数据格式化const tableData = formatData(data, columns);// 2. 构建 HTML 表格字符串let html = 'html xmlns:x=urn:schemas-microsoft-com:office:excel';html += 'head';html += 'meta charset=UTF-8';// 关键：设置工作表名称，避免乱码html += `xmlx:ExcelWorkbookx:ExcelWorksheetsx:ExcelWorksheetx:Name${fileName}/x:Name/x:ExcelWorksheet/x:ExcelWorksheets/x:ExcelWorkbook/xml`;html += '/head';html += 'bodytable border=1';// 3. 遍历数据生成行tableData.forEach((row, index) = {html += 'tr';row.forEach(cell = {// 表头加粗const style = index === 0 ? 'style=font-weight:bold;' : '';// 转义 HTML 特殊字符，防止注入或格式错乱const safeCell = String(cell).replace(//g, 'amp;').replace(//g, 'lt;').replace(//g, 'gt;');html += `td ${style}${safeCell}/td`;});html += '/tr';});html += '/table/body/html';// 4. 创建 Blob 对象const blob = new Blob(['\ufeff', html], {type: 'application/vnd.ms-excel;charset=utf-8;'});// 5. 触发下载saveAs(blob, `${fileName}.xls`);
}逐行讲解重点：\ufeff：这是 UTF-8 BOM（字节顺序标记）。没有它，Excel 打开中文表头大概率会乱码。这是无数新手掉过的坑。
xmlns:x：命名空间声明，告诉 Excel 这是合法的 Office 文档结构。
saveAs：我们稍后封装，这里先假设它存在。3. 文件保存封装：跨浏览器兼容
直接创建 a 标签并点击，在 Safari 等浏览器上可能失效。
我们需要一个更稳健的方案。
// fileSaver.js
export function saveAs(blob, filename) {// 兼容旧版 IEif (navigator.msSaveOrOpenBlob) {navigator.msSaveOrOpenBlob(blob, filename);return;}// 现代浏览器方案const url = window.URL.createObjectURL(blob);const link = document.createElement('a');// 关键：设置下载属性link.href = url;link.download = filename;// 隐藏链接，避免页面跳动link.style.display = 'none';document.body.appendChild(link);// 触发点击link.click();// 清理：移除 DOM 节点，释放内存document.body.removeChild(link);window.URL.revokeObjectURL(url);
}避坑提示：window.URL.revokeObjectURL 必须调用。如果不释放，长时间运行会导致内存泄漏，浏览器内存占用飙升。
在 link.click() 之前，必须确保 link 已经添加到 DOM 中。否则在某些浏览器中点击事件不会触发。运行与测试：如何验证你的代码
代码写完了，怎么测？
别只点按钮看有没有文件下载。你要做断言式测试。
1. 单元测试数据格式化
在 dataFormatter.js 中，你可以简单写一个测试用例：
const testColumns = [{ key: 'name', label: '姓名', type: 'text' },{ key: 'age', label: '年龄', type: 'number' }
];const testData = [{ name: '张三', age: 25 },{ name: '李四', age: null } // 测试空值
];const result = formatData(testData, testColumns);// 预期输出:
// [
// ['姓名', '年龄'],
// ['张三', '25.00'],
// ['李四', '']
// ]console.assert(result[1][1] === '25.00', '数字格式化失败');
console.assert(result[2][1] === '', '空值处理失败');2. 手动测试极端场景
在 Vue 组件中，尝试以下场景：空数据：列表为空时，是否导出一个只有表头的 Excel？
特殊字符：数据中包含 scriptalert(1)/script，导出后是否被转义？
大文件：模拟 10,000 条数据，观察浏览器是否卡顿。如果 10,000 条数据卡顿，说明我们的字符串拼接方式效率不够高，需要优化（见下一节）。
优化扩展：从能用到好用
1. 性能优化：分片处理
当数据量超过 5,000 条时，String 拼接会产生大量内存碎片。
解决方案：使用 Array.join 或者分块生成 HTML。
// 优化后的 generateExcel 片段
const rows = tableData.map(row = {return 'tr' + row.map(cell = `td${cell}/td`).join('') + '/tr';
}).join('');html += rows;join 的性能远优于循环中的 += 拼接。
2. 样式增强：合并单元格
如果需要合并表头，比如“2023年”下面分“1月”、“2月”。
在 HTML 中，使用 colspan 和 rowspan 属性。
你需要在 columns 配置中增加层级结构，然后在生成 HTML 时动态计算跨度。
// 简化示例：假设 columns 是树形结构
// 实际项目中，你需要编写递归函数来计算 colspan3. 错误处理：用户友好提示
在 ExportButton.vue 中，增加 loading 状态和 try-catch。
templatebutton :disabled=loading @click=handleExport{{ loading ? '导出中...' : '导出Excel' }}/button
/templatescript
import { generateExcel } from '@/utils/excelGenerator';export default {props: {data: { type: Array, default: () = [] },columns: { type: Array, default: () = [] }},data() {return {loading: false};},methods: {async handleExport() {if (!this.data.length) {this.$message.warning('暂无数据可导出');return;}this.loading = true;try {// 模拟网络延迟或大数据量处理await new Promise(resolve = setTimeout(resolve, 100));generateExcel({data: this.data,columns: this.columns,fileName: '用户列表'});this.$message.success('导出成功');} catch (error) {console.error('导出失败', error);this.$message.error('导出失败，请重试');} finally {this.loading = false;}}}
};
/script小结：手写实现的价值
通过这篇实战，我们完成了从零到一的过程。
你不仅仅得到了一个导出 Excel 的功能，更掌握了：数据与视图的解耦：格式化逻辑独立，易于测试。
浏览器底层 API 的应用：Blob、URL、DOM 操作的细节。
性能与兼容性的权衡：为什么选 HTML 表格而不是 XLSX 库。
工程化思维：模块化、错误处理、内存管理。新手避坑总结：一定要加 \ufeff 防止中文乱码。
一定要 revokeObjectURL 防止内存泄漏。
一定要处理空值和特殊字符。
不要盲目相信“通用代码”，要根据业务场景调整。你公司项目里是怎么处理导出 Excel 的？是直接用第三方库，还是像这样手写？
欢迎在评论区分享你的踩坑经历，或者贴出你的解决方案，大家一起交流。