做后台管理系统开发的朋友应该都有同感，"把当前表格导出成Excel"这个需求，几乎在每个项目里都会撞见。以前我习惯把活甩给后端，后端拼文件、返回地址、前端触发下载，一条链路看似顺畅，但一旦碰样式就难受了。今天要带个筛选条件、明天表头要多加一行、后天某个列要标红，来回沟通的成本比写代码还高。后来在某个Vue3项目中，我彻底切到了ExcelJS，导出逻辑完整放在前端做，自己取数、自己排版、自己导出，样式随手就能控制，再也不用夹在后端和产品之间传话了。
这篇文章就围绕ExcelJS在Vue3里的"原生导出"和"样式设置"展开，我会从方案选型、样式API拆解、完整模块实现到常见坑位排查，把我实际跑通的一整套东西整理出来。适合正在用Vue3写后台、被导出需求反复折腾的开发者参考。不管你是刚接触ExcelJS还是已经用过但被样式细节卡住，这篇应该都能帮你省下不少时间。
1. 方案选型与整体设计思路
1.1 为什么最终选了ExcelJS而不是其他方案
前端生成Excel的库其实不止一个，早期我试过直接拼HTML表格再转xls的老套路，那玩意生成的文件打开会带格式警告，兼容性也差。也用过一个比较流行的轻量库，它的文件体积确实小，但核心能力是"表格数据序列化"，没有workbook、worksheet这种完整的电子表格对象模型，更别提操作样式。想实现合并单元格、设置冻结窗格、控制某个单元格的字体颜色，它基本上是无能为力的，顶多套一层最原始的样式模板。
ExcelJS吸引我的点，是它建立了一整套完整的Excel对象模型。Workbook对应整个工作簿，Worksheet对应底部标签页，Cell对应每个格子，同时提供了从行列、边框、字体到填充、条件格式、批注、图片的全体系API。这意味着我可以用接近Excel操作习惯的思维方式来写代码，而不是为了导出一个文件去想各种奇技淫巧。它在NPM上的周下载量、社区活跃度和文档完整度也是当时几个候选方案里最稳的。
另外ExcelJS生成的是真正的xlsx文件，基于OpenXML标准，不需要依赖Excel环境，用WPS、Office或者在线文档打开都没问题。这一点在团队协作和跨平台场景里非常重要。后端导出Excel通常要专门部署模板文件、维护服务，而ExcelJS可以全部放在浏览器端完成，对后端资源零占用，甚至可以把导出逻辑沉淀成前端公共模块，以后每个页面复用就行。
1.2 Vue3里的导出架构思路
在Vue3项目里用ExcelJS，我通常不是把它直接散落在各个业务组件里，而是单独做一个导出模块。这个模块做的事情是：接收原始数据、接收列配置、内部完成workbook的创建、sheet数据的填充、样式的批量应用，最后统一输出Blob文件。业务组件只需要传数据和配置，不用关心Excel细节。
这样设计的好处很明显：一是样式逻辑收敛在一个地方，以后调表头颜色、换字体，不用每个页面都去改；二是统一的入口方便做扩展，比如批量导出多个sheet、导出带图片的报表，都能在模块层面集中处理。我习惯把列配置定义成数组，每项包含字段名、表头文字、列宽、对齐方式、数字格式等元信息，然后由导出模块统一解析，这样的扩展性最好。
在实际项目中，导出模块还会处理好几个跨页面通用的细节，比如文件命名加日期、导出成功后的用户提示、大数据量场景下前端分批处理的逻辑等。这些看起来是小点，但散落在每个页面里写很容易不一致，集中放在模块里会省心很多。
2. ExcelJS样式体系逐项拆解
2.1 从单元格对象说起
ExcelJS的样式操作核心单元是Cell。每个Cell本身是一个对象，上面挂着一系列样式相关的属性：font、alignment、border、fill、numFmt，以及保护相关的lock等。操作方式很直接，拿到单元格对象后直接给属性赋值，例如：
const cell = sheet.getCell('A1'); cell.value = '标题'; cell.font = { name: '微软雅黑', size: 14, bold: true, color: { argb: 'FFFF0000' } };这里面有个细节值得注意：ExcelJS的字体颜色、填充颜色这类颜色值使用的是ARGB格式，也就是8位十六进制，最前面两个字节是Alpha通道，实际写的时候通常直接写FF加6位色值。很多人第一次用会写#FF0000，或者只写6位色值，结果颜色不生效，就是这个原因。
颜色值同样适用于边框、填充。另一个习惯是先定义好一个样式对象，再赋给多个单元格，避免一个个手写。不过这里有个需要意识到的点：赋值的是对象引用，后续如果修改这个对象，已经赋过值的单元格样式也会跟着变。如果希望每个单元格独立，建议用浅拷贝的方式处理。
2.2 字体、对齐与填充的完整参数
字体这块，常用属性包括name（字体名）、size（字号）、bold（加粗）、italic（斜体）、underline（下划线）、color（颜色）。实际项目里最常用的就是中文环境中设置微软雅黑或者宋体，表头加粗。这里有一个中文场景容易踩的坑：如果导出文件在别人电脑上打开，但对方机器没有你在代码里指定的字体，Excel/WPS会自动替换成默认字体，导致排版看起来不一样。所以在字体选择上尽量用通用性强的字体。
对齐方式通过alignment属性配置，常用的包括：
cell.alignment = { horizontal: 'center', // 水平：left、center、right、fill、justify、centerContinuous vertical: 'middle', // 垂直：top、middle、bottom wrapText: true, // 是否自动换行 textRotation: 0, // 文字旋转角度 indent: 1 // 缩进 };horizonta和vertical这里特别容易写错拼写，我发现实际项目里很多坑都是拼写导致样式不生效。另外wrapText: true这个属性很实用，像地址、描述这类长文本列，有了自动换行才能保证行高撑开，内容不会溢出到旁边格子。
填充样式分为两种模式，最常用的是纯色填充：
cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFF4B183' } };如果要做渐变或者双色斜纹效果，需要调整pattern为其他枚举值，但实际业务报表里很少用到。表头加底色、奇数偶数行交替配色、合计行标灰，用solid模式就完全够用了。这里补充一下：fgColor是前景色，在solid模式里就是你看到的主颜色，bgColor是背景色，在pattern模式下才会作为衬底颜色显示，不要搞反了。
2.3 边框、合并与冻结
边框是最能体现表格"专业感"的样式。默认导出的Excel是没有边框的，数据一多看起来就像散装文本。ExcelJS里边框分上下左右四个方向，每个方向可以设置style和color：
cell.border = { top: { style: 'thin', color: { argb: 'FF000000' } }, left: { style: 'thin', color: { argb: 'FF000000' } }, bottom: { style: 'thin', color: { argb: 'FF000000' } }, right: { style: 'thin', color: { argb: 'FF000000' } } };style支持的值包括thin、medium、thick、dashed、dotted、double等，日常报表用thin就够，合计行上方用medium或thick做分隔线会更有层次感。这里有一个效率上的建议：与其给每个单元格单独设置四边，不如按行列批量遍历设置，后面我会在实操部分给出具体写法。
合并单元格在报表里非常常见，比如大标题跨多列、分组表头跨两行。ExcelJS里合并操作很简单：
sheet.mergeCells('A1:F1');合并之后，值只需要写在合并区域左上角那个单元格里，其他单元格会变成合并区域的一部分，不能再单独赋值。如果有边框需求，合并后只需要给左上角单元格设置边框，整块合并区域会统一渲染。这里有个小坑：合并单元格后，再通过getCell去拿区域内其他格子的值会拿到null，因为它们在合并区里没有独立存在。遍历数据时要注意别去操作合并区域内的其他单元格。
冻结窗格也是后台报表的高频需求，尤其数据行数多的时候。配置方式如下：
sheet.views = [{ state: 'frozen', xSplit: 1, ySplit: 1 }];xSplit和ySplit分别表示冻结列数和冻结行数。比如ySplit: 1是冻结第一行表头，滚动数据时表头永远可见。配合xSplit: 1可以同时冻结第一列，适合字段多、需要横向滚动的宽表。注意这个赋值是给整个sheet的view配置，而不是某一行或某一列。
2.4 行列级别的样式控制
除了单元格，ExcelJS还支持行列级别的操作，这在设置列宽、行高和整行整列样式时非常高效。
列宽设置有两种方式。一种是在定义columns时直接带width：
sheet.columns = [ { header: '姓名', key: 'name', width: 15 }, { header: '年龄', key: 'age', width: 8 } ];另一种是后续通过列索引调整某个列宽度：
sheet.getColumn(3).width = 20;行高默认情况下Excel会根据内容自动调整，但设置了固定行高后，内容再多也不会撑开。所以如果某个列开了自动换行，建议给对应的行设置足够的高度，或者干脆不设置行高让它自适应。需要给所有数据行统一样式时，可以遍历行：
sheet.eachRow((row, rowNumber) => { row.height = 22; row.eachCell((cell) => { cell.alignment = { vertical: 'middle' }; }); });注意eachRow遍历的范围默认是存在内容的行。如果中途通过row.height = ...设置了高度，但这个行本身没有数据，遍历时不会到达。更保险的做法是先填完所有数据，最后再统一处理样式。
3. 从零搭建带样式的导出模块
3.1 安装与基础封装
安装ExcelJS很简单，一条命令：
npm install exceljs它有自己的TypeScript类型定义，Vue3项目一般也都用TS，类型提示很全。初始化一个workbook的常规流程是：
import ExcelJS from 'exceljs'; const workbook = new ExcelJS.Workbook(); workbook.creator = '某公司前端导出模块'; workbook.created = new Date();creator和created这两个属性会写入文件元信息，虽然不是必须的，但每次导出都带上，方便文件管理。接着添加工作表：
const sheet = workbook.addWorksheet('数据报表', { properties: { defaultRowHeight: 20 } });工作表名称有长度限制，而且不能包含\ / ? * [ ] :这些字符，命名的时候最好做一层校验。addWorksheet的第二个参数还支持很多配置，比如views冻结设置、pageSetup打印设置、tabColor标签页颜色，这些按需使用。
3.2 表头与标题区的处理
实际项目中，一份稍微像样的报表通常会有一个总标题、一个表头行，再加数据区。我用一个完整的导出函数来演示，它接收数据数组和列配置数组：
function exportExcel(rows, columns, fileName) { const workbook = new ExcelJS.Workbook(); const sheet = workbook.addWorksheet('Sheet1'); // 列配置 sheet.columns = columns.map(col => ({ header: col.title, key: col.field, width: col.width || 15 })); // 添加标题行并合并 const titleRow = sheet.addRow(['销售数据报表']); sheet.mergeCells(`A1:${sheet.getColumn(columns.length).letter}1`); titleRow.height = 30; const titleCell = sheet.getCell('A1'); titleCell.font = { size: 16, bold: true }; titleCell.alignment = { horizontal: 'center', vertical: 'middle' }; // ... }这里有个关键点：sheet.columns设置了列头信息之后，sheet.addRow添加数据会自动按照配置里的key和header来映射。但如果我们顶部插入了标题行，表头行的位置会往下挪。纯用addRow的话，ExcelJS会默认把第一行当成表头并写入header值，这与我们插入标题行会有冲突。所以这里建议换一种处理方式：先通过getRow拿到指定行号，手动赋值单元格。
const headerRow = sheet.getRow(2); columns.forEach((col, index) => { const cell = headerRow.getCell(index + 1); cell.value = col.title; cell.font = { bold: true, color: { argb: 'FFFFFFFF' } }; cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF4472C4' } }; cell.alignment = { horizontal: 'center', vertical: 'middle' }; }); headerRow.height = 24;这种手动定位行的方式虽然代码多一点，但对于复杂报表的排布其实更可控。表头背景色我一般用深蓝色系、白字加粗，打开后视觉效果比较清晰。
3.3 数据区的样式编排
数据区紧跟着表头往下排。最简单的方式是把原始数据逐行addRow，再统一设置样式。逐行添加有一个好处：ExcelJS会根据sheet.columns的key自动匹配每个字段填充到对应列，字段缺失就留空，不用担心列错位。
rows.forEach(item => { sheet.addRow(item); });但这里有个"样式会话"的细节：如果先全部加完数据，再遍历设置样式，数据量大时会产生多次对象访问；如果每加一行立刻设置该行样式，代码会显得重复。我的做法是先把数据全部写入，再统一遍历处理样式，这样逻辑清晰，性能也更可控。
sheet.eachRow((row, rowNumber) => { if (rowNumber <= 2) return; row.height = 22; row.eachCell(cell => { cell.border = { top: { style: 'thin', color: { argb: 'FFD9D9D9' } }, left: { style: 'thin', color: { argb: 'FFD9D9D9' } }, bottom: { style: 'thin', color: { argb: 'FFD9D9D9' } }, right: { style: 'thin', color: { argb: 'FFD9D9D9' } } }; cell.alignment = { vertical: 'middle', horizontal: 'center' }; }); });交替行配色我习惯通过判断行号奇偶来实现：
sheet.eachRow((row, rowNumber) => { if (rowNumber > 2 && rowNumber % 2 === 0) { row.eachCell(cell => { cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFF2F6FC' } }; }); } });这里有个性能上的考虑：如果是几千行的大表，eachRow加eachCell遍历单元格的次数会非常多。可以改为按整行设置样式，ExcelJS会把这些样式记录在行级别，而不是逐个格子都存一份样式对象，文件体积和内存占用都会收敛不少。
数字格式是容易被忽略但很重要的部分。金额、百分比、日期这些类型如果没有正确设置numFmt，导出后要么变成一串数字，要么是时间戳格式，看起来很业余。比如金额列：
cell.numFmt = '#,##0.00';日期列：
cell.numFmt = 'yyyy-mm-dd';百分比列：
cell.numFmt = '0.00%';这些格式等同于Excel里的"设置单元格格式-数字-自定义"效果。日期类还有一个坑：ExcelJS中写入日期建议用new Date()对象，底层会自动做OADate序列化，但需要配合numFmt才会显示成年月日，否则打开就是原始数字。
3.4 收尾：workbook到文件的完整流程
所有数据和样式都填充完毕后，生成文件有统一的收尾流程：
const buffer = await workbook.xlsx.writeBuffer(); const blob = new Blob([buffer], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }); const url = URL.createObjectURL(blob); const link = document.createElement('a'); link.href = url; link.download = `${fileName || 'export'}.xlsx`; link.click(); URL.revokeObjectURL(url);writeBuffer在不同版本里返回类型略有差异，有些需要buffer或处理二进制类型，但现代浏览器环境下使用这个方法基本都是稳的。URL.revokeObjectURL一定要在a.click()之后调用，否则部分浏览器可能还没完成下载就已经把地址回收了。
文件名方面我会在模块内部拼上当前日期，比如销售报表_20250718.xlsx，这样导出多份不会互相覆盖。这里有个容易出问题的点：如果文件名包含中文，直接给link.download赋值是没问题的，现代浏览器都能处理；但如果项目通过接口下载头部Content-Disposition，就需要额外处理URL编码，反正ExcelJS方案不走接口，省掉了这层麻烦。
4. 常见问题与排查经验
4.1 样式被覆盖是最大的坑
实际开发中，"明明设置了样式，打开文件却没有"这类问题出现频率最高。排查下来大部分原因是对同一个单元格的样式属性做了多次赋值，后一次赋值覆盖了前一次的部分字段。比如先赋了font，后面又整体赋了一个新的font对象，这个新对象里漏掉了color，颜色就丢了。
有一种情况特别隐蔽：ExcelJS大概在3.x版本之后有了styles管理机制，同一个单元格如果先设置fill，再设置font，正常不会互相影响。但如果你在一次循环里先给单元格赋值cell.value，随后马上设置样式，而这个单元格之前已经被其他逻辑赋过样式，则完全覆盖的风险就存在。
我的习惯是每个单元格的样式统一用一次对象赋值完成，而不是拆成多次。如果确实需要分步设置，每次都显式把需要的字段写全。另外，尽量用cell.style = {...}直接覆盖整个样式对象，比一个个cell.font = ...、cell.fill = ...更可控。不过cell.style在旧版本里支持，新版API推荐直接断言属性，具体以当前版本为准，两种方式都可以。
4.2 列宽、行高的单位问题
ExcelJS里列宽和Excel界面上的显示表现有差异。Excel界面上看到的列宽单位是英文字符数，ExcelJS用的是这个逻辑的近似值。如果你设置width: 20，打开Excel后大概就是20个字符的宽度。中文字符比英文字符宽，所以如果传输中文列，需要手动加大width系数，不然中文会显示不全。我的经验是中文表头宽度系数给1.5左右，比如"操作人"这种列给15到18，打开就能完整显示。
行高方面，ExcelJS的默认单位是磅（point），和Excel的行高是同一套体系，所以不需要额外换算。但如果某个单元格字体比较大、内容超过两行而设置了固定行高，内容会被截断显示。这时要么去除该行的高度设置，要么在设置wrapText: true的同时手动把行高算到足够容纳内容的值。一个粗暴但有效的做法是依据该行可能最长的字段字数乘上一个估算系数，设置足够大的行高。
4.3 大数据量的性能优化
当数据量达到几千行甚至上万行时，逐格设置样式会有明显的卡顿。ExcelJS本身在前端做序列化需要时间，样式越多、writeBuffer的耗时越长，这是正常的，但仍有一些优化空间。
首先是样式压缩：尽量复用同一个样式对象，不要每行都创建新的。比如交替色、边框、对齐方式这些，分别抽成常量，循环里只把常量赋值给单元格，ExcelJS内部会根据样式内容做去重处理，文件体积明显变小，生成速度也能快一些。
其次避免频繁调用getCell这种按坐标取单元格的方式，在eachRow里用row.eachCell或直接按row.getCell(index)更高效。上万行数据时节点遍历的调用次数是几何级增长的，任何多余操作都会被放大。
如果数据量真的巨大，比如说几十万行，前端导出本身就是不合理的方案。这种场景应该限制导出条数，或者在后端做异步导出任务。ExcelJS虽然有stream写文件的能力，但在浏览器端受限于jszip的内存开销，稳定性并不好，不如在服务端做。
4.4 文件损坏、日期序列化等其他杂症
配置了合并单元格后生成文件打不开，或者打开提示"文件已损坏"，多数原因是合并区域跨度过大并且区域内左上角单元格无值，或者合并区域与其他合并区域产生了重叠冲突。ExcelJS不会在生成时主动检测这种逻辑错误，需要自己确认。常见错误比如mergeCells('A1:C1')后又对B1单独赋值，或者两个合并区域部分重叠，都会导致文件结构异常。
日期序列化问题前面提到过，不设置numFmt、直接赋值Date对象会变成OADate数字。还有一种情况是后端接口返回的日期是字符串格式，ExcelJS不会自动识别为日期，导出后就是文本。要在前端先转成Date对象再赋值。注意时区问题，如果项目有UTC偏移处理，转成Date对象后写入Excel的日期可能与预期相差8小时，最好确认接口返回的时间字段已经经过了统一处理。
还有一点：如果单元格的值以=开头，ExcelJS会把整段内容当作公式处理。比如导出分类编号=精装这种文本，打开文件时会显示为公式错误。需要转成字符串的格式。处理方案有两种：一种是写入时手动加单引号前缀，Excel打开时会当作文本；另一种是使用cell.value = { text: '=精装' }这种对象形式写入。后者是更明确的写法。
4.5 表格视图、打印设置与隐藏列
这部分不算坑，但用好了很加分。如果报表打开后希望用户第一眼就看到特定区域，可以用sheet.views配置缩放比例：
sheet.views = [{ zoomScale: 90 }];导出前如果希望隐藏某些辅助列，比如ID字段，可以设置列隐藏：
sheet.getColumn(1).hidden = true;打印场景下，通过pageSetup设置横向打印、A4纸、缩放比例，可以让报表打印出来不带多余的空白页：
sheet.pageSetup = { orientation: 'landscape', fitToPage: true, fitToWidth: 1, fitToHeight: 1, paperSize: 9 // A4 };这些配置都是元数据级别的，不会影响导出内容，但对用户体验和之后的纸质归档很有帮助。我一般在通用导出模块里默认把fitToWidth设置为1，这样无论多少列，打印时总会缩到一页宽，避免打印出来被切掉大半。
5. 导出模块的整体收益与后续扩展
Vue3 + ExcelJS这套组合，对我来说最大的收益是"真正把导出这个能力还给了前端"。产品提需求、改样式，我直接在组件里改配置，一条数据流的改动，几分钟重新导出验证，整个迭代效率比之前跨团队沟通高很多。对中小型团队来说，沉淀一个导出模块能覆盖绝大多数报表页面，性价比相当高。
扩展方向也很明确。比如多sheet导出，workbook.addWorksheet可以创建多个工作表，每个sheet里放一组数据，一键生成月度汇总文件。又比如导出带图片的报表，workbook.addImage加sheet.addImage就能在指定位置插入Logo、签名或者数据图片，配合editAs参数控制图片锁定于单元格或浮于上方。另一个常用扩展是数据校验，sheet.dataValidations可以为某列设置下拉选项，这在做模板类导出时特别有用。
我个人在实际操作中的体会是：ExcelJS的API设计挺贴合Excel本身的逻辑，学习成本不高，真正的难点在细节。颜色搞错格式、样式被覆盖、日期变序列号、合并区域重叠，这些坑每个都会浪费一两个小时。但只要你把这些经验固化到统一模块里，后面基本就是一劳永逸。这篇内容里涉及的代码片段，我在项目里都反复用过，组合起来可以直接搭出一套够用的导出能力。如果你也正在Vue3项目里捣鼓Excel导出，照着这套思路去封装，应该能避开我踩过的大部分坑位。
