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 += `<xml><x:ExcelWorkbook><x:ExcelWorksheets><x:ExcelWorksheet><x:Name>${fileName}</x:Name></x:ExcelWorksheet></x:ExcelWorksheets></x:ExcelWorkbook></xml>`;html += '</head>';html += '<body><table 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？
特殊字符：数据中包含 <script>alert(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 是树形结构
// 实际项目中，你需要编写递归函数来计算 colspan

3. 错误处理：用户友好提示

在 ExportButton.vue 中，增加 loading 状态和 try-catch。

<template><button :disabled="loading" @click="handleExport">{{ loading ? '导出中...' : '导出Excel' }}</button>
</template><script>
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>