尧图网页设计 
Spring Boot Vue 前后端分离实现导出 Word 文档实战在办公类系统里“导出 Word”绝对是出现频率最高的需求之一。合同、报告、审批单、简历、测试报告业务方经常会说“我要能下载一份正式的 Word 文档格式要能直接编辑”。如果你用的是 Spring Boot Vue 这套前后端分离架构那导出 Word 这件事就有不少细节值得讲清楚——从后端怎么生成真正的 .docx 文件到前端怎么把二进制流完整接住并触发下载中间踩过的坑、走过的弯路我今天一次性理清楚。先说结论基于 Spring Boot 后端生成 Word 文件前端通过接口以二进制流方式下载是目前前后端分离项目里最稳定、最通用的实现路径。这可能和有些同学的直觉不一样——既然 Vue 是前端框架为什么不在前端直接生成 Word我在项目里也试过纯前端方案比如 html-docx-js 这类库小场景确实能用但一旦涉及页码、复杂表格、页眉页脚、服务端模板统一管理前端方案就非常吃力渲染效果也容易跑偏。更关键的是生成文件的逻辑放在后端可以统一处理模板、权限、历史版本换任何前端都能复用同一套接口这才是企业级项目的正确姿势。这篇文章会以一个真实项目为例带你完整走一遍 Spring Boot Vue 导出 Word 的落地过程先讲方案选型背后的考量再拆后端核心实现然后说前端怎么接流最后把高频问题做一个排查手册。无论你是刚接手这类需求的新人还是想优化现有实现的老手这篇都能给你一些可以直接抄作业的东西。1. 整体方案设计与技术选型1.1 为什么选择后端生成 Word 而不是前端生成先聊方案。接到“导出 Word”这个需求第一反应往往不是选技术而是回答一个更根本的问题这份 Word 的内容和格式是固定的还是动态的如果是固定的合同模板、报告模板格式要求严格那模板 占位符替换是首选如果内容完全是动态拼接格式不复杂那可以用代码直接构建文档。在前后端分离架构下我更推荐把生成动作放在后端原因有三个第一模板统一管理。企业的 Word 模板往往需要法务、行政、业务部门反复修改放在后端资源目录里改一次所有用户立即生效。前端生成的话每次模板调整都要发版这是不能接受的。第二数据安全性。导出内容通常涉及业务数据用户有没有权限看这些数据应该由后端校验。数据在服务端生成好了再下发权限问题天然可控。第三跨端一致性。同一个系统可能有 Web 端、管理后台、甚至未来有小程序后端接口一套搞定各端只是触发同一个下载动作而已。1.2 后端生成 docx 的几条技术路线对比确定后端生成之后技术选型又是一个关键节点。我整理一下 Java 生态常见的几种方式方便你做对比。方案特点适用场景Apache POI 原生 API底层、灵活、可控性最强能操作 Word 的段落、表格、图片、样式需要精细控制文档结构且对性能、依赖有一定要求的项目POI 模板占位符替换提前做好 .docx 模板用工具或手写代码替换 ${xxx}格式固定的合同、报告类场景开发效率高poi-tlPOI Template Language基于 POI 封装专为模板引擎设计语法简单功能强大业务模板复杂频繁迭代希望减少样板代码easypoi注解式导出类似 easyexcel支持 Word 导出对格式要求不高追求快速开发的简单导出jacob / comtypes 调用本机 Word需要安装 Office依赖 Windows 环境性能差已经在用 Windows 服务器的老项目私有化部署我的建议是如果只是简单几段文字POI 手搓就够了如果是正经的合同、报告的模板导出直接用 poi-tl 能少写很多代码。后面我会把这两种方式都展开演示。1.3 Spring Boot 版本与依赖引入的踩坑提示这里必须提一个高频坑springboot版本太高。我见过不少项目用 Spring Boot 3.x结果引入 POI 相关依赖时出现ClassNotFoundException或者包冲突原因大多是版本兼容问题。Spring Boot 3.x 基于 Jakarta EE某些旧版本的 POI 工具库内部用了javax命名空间就挂了。安全组合是Spring Boot 2.7.x POI 5.x或者 Spring Boot 3.x POI 5.2.2 以上版本。如果你打算用 poi-tl特别注意 poi-tl 1.12.x 适配 POI 5.x别拿到旧版本 poi-tl 硬配 POI 5.x那会编译都过不去。依赖引入以 Maven 为例核心只要两个dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.5/version /dependency dependency groupIdcom.deepoove/groupId artifactIdpoi-tl/artifactId version1.12.1/version /dependencypoi-tl 自带 POI 依赖理论上加了 poi-tl 就能跑但我习惯显式声明 poi-ooxml 版本避免传递依赖把版本带歪。2. 后端核心实现模板导出与动态生成2.1 基于 poi-tl 的模板占位符方案现在说正事。假如业务方给了一个 docx 模板里面有合同编号、甲方、乙方、签署日期这些字段你只需要在对应位置写上${contractNo}、${partyA}、${partyB}、${signDate}后端拿到数据填充即可。poi-tl 的渲染代码非常简洁import com.deepoove.poi.XWPFTemplate; import com.deepoove.poi.data.Pictures; import java.io.FileOutputStream; import java.io.IOException; import java.util.HashMap; import java.util.Map; public class WordExportService { public void exportContract(String templatePath, String outputPath, String contractNo, String partyA, String partyB) throws IOException { // 1. 准备数据 MapString, Object data new HashMap(); data.put(contractNo, contractNo); data.put(partyA, partyA); data.put(partyB, partyB); data.put(signDate, 2024-06-01); // 2. 渲染模板 XWPFTemplate template XWPFTemplate.compile(templatePath) .render(data); // 3. 写出文件 template.writeToFile(outputPath); template.close(); } }就这么简单。poi-tl 底层仍然是 POI但它把“打开文档 - 查找占位符 - 替换文本/图片/表格 - 保存”这套流程封装好了。你不需要关心 XWPFDocument 的段落遍历、Run 对象的细节。需要说明的是占位符渲染时默认不会继承原占位符的所有样式而是沿用模板里该位置的段落样式。所以模板里多写几行示例文字样式调好再把文字替换成${xxx}最终效果基本是所见即所得。2.2 原生 POI 构建复杂表格设置 Word 表格列宽如果不想引入 poi-tl或者要生成动态行数的表格那原生 POI 是躲不掉的。表格是 Word 导出里最容易翻车的部分而且热搜词里就有“poi设置word表格单元格宽度”和“word 表格列宽无法拖动”可见这个点确实困扰了不少人。用 POI 创建表格的核心代码如下import org.apache.poi.xwpf.usermodel.*; public class TableWordService { public void createReportWithTable(String outputPath) throws Exception { try (XWPFDocument document new XWPFDocument()) { // 1. 创建 2 行 4 列的表格后续可动态插入行 XWPFTable table document.createTable(2, 4); // 2. 设置表格整体宽度单位Twips1 厘米约等于 567 Twips table.setWidth(100%); // 3. 设置每一列的列宽必须先设置 tblLayout 为固定布局否则列宽不生效 table.getCTTbl().getTblPr().setTblLayout( org.openxmlformats.schemas.wordprocessingml.x2006.main.CTTblLayoutType.Factory.newInstance() ); // 表格首行填充数据 XWPFTableRow headerRow table.getRow(0); String[] headers {项目, 数量, 单价, 备注}; for (int i 0; i headers.length; i) { headerRow.getCell(i).setText(headers[i]); // 设置单元格宽度 headerRow.getCell(i).setWidth(2000); } // 4. 动态插入数据行 XWPFTableRow dataRow table.createRow(); dataRow.getCell(0).setText(笔记本电脑); dataRow.getCell(1).setText(2); dataRow.getCell(2).setText(5999); dataRow.getCell(3).setText(固定资产); // 5. 保存 try (java.io.FileOutputStream fos new java.io.FileOutputStream(outputPath)) { document.write(fos); } } } }这里有两个关键坑必须先说列宽不生效直接调getCell(i).setWidth(2000)只在某些 Word 版本里有效。更稳的方式是先设置表格的tblLayout为fixed否则 Word 会根据内容自动调整列宽你设置的数值会被无视。上面代码里已经加了这段。单元格宽度单位POI 的宽度单位是 Twips缇1 英寸 1440 Twips1 厘米约等于 567 Twips。你可能看到很多代码写的是字符串数字比如2000这不是 2000 像素而是 2000 Twips相当于约 3.5 厘米。需要用CTTcPr底层的setTcw来精确设置但大多数场景下setWidth已经够了。2.3 动态行表格生产环境的完整 Service 代码上面只是片段。真实项目中表格行数往往是运行时才知道的比如导出员工列表、订单列表。我习惯这样组织 ServiceService public class ReportExportService { public void exportEmployeeReport(ListEmployee employees, OutputStream outputStream) throws Exception { try (XWPFDocument document new XWPFDocument()) { // 标题 XWPFParagraph title document.createParagraph(); title.setAlignment(ParagraphAlignment.CENTER); XWPFRun titleRun title.createRun(); titleRun.setText(员工信息报告); titleRun.setBold(true); titleRun.setFontSize(18); // 说明段落 XWPFParagraph desc document.createParagraph(); desc.setAlignment(ParagraphAlignment.LEFT); XWPFRun descRun desc.createRun(); descRun.setText(导出时间 LocalDate.now()); descRun.setFontSize(10); // 表格 XWPFTable table document.createTable(employees.size() 1, 4); table.setWidth(100%); // 设置固定布局防止列宽丢失 table.getCTTbl().getTblPr().setTblLayout( org.openxmlformats.schemas.wordprocessingml.x2006.main.CTTblLayoutType.Factory.newInstance() ); // 设置表头 String[] headers {工号, 姓名, 部门, 岗位}; for (int i 0; i headers.length; i) { XWPFTableCell cell table.getRow(0).getCell(i); cell.setText(headers[i]); cell.setWidth(1500); } // 填充数据行 for (int i 0; i employees.size(); i) { Employee emp employees.get(i); XWPFTableRow row table.getRow(i 1); row.getCell(0).setText(emp.getEmployeeNo()); row.getCell(1).setText(emp.getName()); row.getCell(2).setText(emp.getDepartment()); row.getCell(3).setText(emp.getPosition()); } document.write(outputStream); } } }Controller 层直接把这个 OutputStream 对接到 HttpServletResponseRestController RequestMapping(/api/export) public class ExportController { private final ReportExportService exportService; public ExportController(ReportExportService exportService) { this.exportService exportService; } GetMapping(/word/employee) public void exportEmployeeWord(HttpServletResponse response) throws Exception { ListEmployee employees employeeService.listAll(); response.setContentType(application/vnd.openxmlformats-officedocument.wordprocessingml.document); response.setCharacterEncoding(UTF-8); String fileName URLEncoder.encode(员工信息报告_ LocalDate.now() .docx, UTF-8); response.setHeader(Content-Disposition, attachment; filename*UTF-8 fileName); exportService.exportEmployeeReport(employees, response.getOutputStream()); } }这里注意一下Content-Disposition里对文件名做了 URL 编码。这是前端能正确拿到中文文件名的基础后面会再细说。2.4 图片插入带签章或附件的常见写法Word 文档里经常要插入图片比如公司 Logo、签名图片、产品截图。poi-tl 里用Pictures.of()很方便import com.deepoove.poi.data.PictureRenderData; import com.deepoove.poi.data.Pictures; // 模板里写 {{logo}} data.put(logo, Pictures.of(/path/to/logo.png).size(120, 60).create());原生 POI 也不难用XWPFRun.addPicture即可XWPFParagraph paragraph document.createParagraph(); XWPFRun run paragraph.createRun(); try (InputStream is new FileInputStream(/path/to/sign.png)) { run.addPicture(is, XWPFDocument.PICTURE_TYPE_PNG, sign.png, Units.toEMU(80), Units.toEMU(40)); }注意addPicture的宽高单位是 EMU直接用像素不行。POI 提供了Units.toEMU()来做转换。很多同学在这一步图片变形或者不显示基本都是单位没用对或者图片流没有关闭导致文件损坏。3. 前端 Vue 实现文件下载的完整流程3.1 Axios 设置 responseType 和 token后端接口好了前端要接得住这个文件流才行。Vue 项目一般都用 axios最关键的设置有两点responseType: blob告诉 axios 把响应体当二进制流处理而不是默认的 JSON。带上鉴权 header项目里一般有 token 拦截器。看代码import axios from axios export function downloadEmployeeWord(params) { return axios({ url: /api/export/word/employee, method: get, params, responseType: blob, // 核心必须以 blob 形式接收 timeout: 30000 // 导出可能较慢给足时间 }) }如果你的 axios 实例统一在拦截器里加 token那这里不需要重复处理。但一定要确认拦截器没有对 blob 做 JSON 解析。我踩过一次坑响应拦截器里统一做了response.data JSON.parse(response.data)结果导出 Word 时直接报错因为二进制流转 JSON 必挂。后来在拦截器里加了一个判断service.interceptors.response.use( (response) { // 判断是否为二进制流 if (response.data instanceof Blob) { return response } // 其他逻辑 return response.data }, (error) { return Promise.reject(error) } )这个判断很关键。因为后端出错时返回的往往不是 Blob而是 JSON 错误信息前端需要区分这两种情况避免把错误信息当文件下载下来。3.2 Blob 下载与文件名中文乱码处理拿到response后需要把它转成下载动作。最关键的就是从Content-Disposition响应头里解析文件名。function getFileName(disposition) { if (!disposition) return 导出文件.docx // 从 filename*UTF-8xxx 中提取 let result disposition.match(/filename\*UTF-8([^;])/i) if (result result[1]) { try { return decodeURIComponent(result[1]) } catch (e) { return 导出文件.docx } } // 兼容 filenamexxx.docx 的旧写法 result disposition.match(/filename?([^]*)?/i) return result ? result[1] : 导出文件.docx } export async function handleDownloadEmployeeWord(params) { try { const response await downloadEmployeeWord(params) // 服务端返回错误时是 JSON需要先判断 if (response.data.type application/json) { const reader new FileReader() reader.onload () { const errorData JSON.parse(reader.result) Message.error(errorData.message || 导出失败) } reader.readAsText(response.data) return } const blob new Blob([response.data], { type: application/vnd.openxmlformats-officedocument.wordprocessingml.document }) const fileName getFileName(response.headers[content-disposition]) const link document.createElement(a) link.href URL.createObjectURL(blob) link.download fileName document.body.appendChild(link) link.click() document.body.removeChild(link) URL.revokeObjectURL(link.href) } catch (error) { Message.error(导出失败请稍后重试) } }代码不算复杂但有三个细节值得展开第一filename*和filename的区别。后端设置了filename*UTF-8xxx这表示经过 URL 编码的文件名中文能正常传输。如果后端只写了filename员工信息报告.docx那是 ISO-8859-1 编码中文在 HTTP 头里会乱码前端拿到就是一堆问号。所以前后端配合时必须统一用filename*。第二blob.type 要设置对。不设置虽然也能下载但文件类型标识不对可能导致 Word 打开时提示文件损坏或格式不兼容。docx 对应的 MIME 类型是application/vnd.openxmlformats-officedocument.wordprocessingml.document这个字符串很容易记错我每次都是直接复制。第三创建a标签后要手动 append 到 body 再 click最后移除。这是为了兼容 Firefox 老版本。现代浏览器不加也能用但加上最稳。3.3 部署环境中的额外注意事项前端部署后如果用的是 Nginx还需要注意代理配置。/api路径要正确代理到后端服务并且proxy_buffering需要开启默认就是开着的否则大文件下载可能被截断。另外如果你发现下载的文件打不开、提示“文件已损坏”先别急着怀疑代码先看文件大小。后端导出的 docx 如果只有 1KB 不到大概率是返回了 JSON 错误信息只是它被保存成了 .docx 后缀。这时候用文本编辑器打开那个文件看看内容是不是{code:500,message:...}这是最直接的排查方式。4. 常见问题与排查技巧实录4.1 文件损坏或打不开这是导出 Word 类需求最高频的报错。可能的原因有很多我按排查优先级列一下症状可能原因解决办法文件只有 1KB用文本打开是 JSON后端异常被前端存成 docx前端判断response.data.type application/json显示错误信息文件大小正常但打开报错模板本身损坏用 Word 打开原模板另存为新的 docx 再试试文件下载中途断开后端没有及时 flush OutputStream或超时设置太短Service 里document.write(outputStream)后立即flush()调大 axios timeout打开时提示“权限”或“内容错误”代码里关闭流时把文档写坏了检查是否在try-with-resources管理 XWPFDocument避免重复关闭这里特别提醒一个点HSSF/XWPF 系列导出 Word 时document.write(outputStream)之后不要再对 response 做任何 setContentType 二次设置否则会破坏已经写好的响应头导致文件内容不完整。我遇到过一次Controller 方法里有个CrossOrigin注解配合过滤器又写了一次响应头文件就坏了。4.2 中文文件名乱码文件名乱码基本是 Content-Disposition 头的问题。我习惯在后端统一这样设置String fileName URLEncoder.encode(员工信息报告.docx, UTF-8); response.setHeader(Content-Disposition, attachment; filename\ fileName \; filename*UTF-8 fileName);filename给一个 ASCII 转义版本URL 编码后的字符串filename*给标准 RFC 5987 格式。这样老浏览器也能解析现代浏览器优先用filename*中文就不会乱。4.3 Word 表格列宽无法拖动/设置不生效表格列宽是另一个重灾区。我在 2.2 里已经给了核心代码这里再说一个常见场景模板里的表格列宽在 Word 里无法拖动。这往往是因为模板本身设置了“固定列宽” 自动调整被禁用。处理方式是在模板阶段就把表格布局设置为“自动调整”或者在 POI 里显式设置列宽。如果用 poi-tl 渲染表格并希望列宽固定可以给表格的每一列设置gridSpan或tcW。poi-tl 官方文档里提到可以用Configure来自定义表格策略但大多数情况下原生 POI 的setWidth已经足够。4.4 Word 关闭时卡顿和导出代码有没有关系热搜词里有一条“word关闭时卡顿”很多同学担心是自己导出的文件有问题。说实话这个概率很低。Word 关闭卡顿通常是本机软件问题比如加载项、缓存问题。但有一种情况和你导出的文件有关文件里嵌入了大量高清图片且未压缩文档体积达到几十 MB。打开这样的文档Word 内存占用高关闭时卡顿是正常的。如果你导出报告包含图片建议在插入前先压缩图片尺寸或者在插入时限制图片显示大小。POI 中Pictures.of().size(width, height)只控制显示尺寸原始图片体积不变所以尽量在源头控制图片文件大小。4.5 Spring Boot 版本太高引发的依赖问题Spring Boot 3.x 用户如果遇到 POI 相关NoClassDefFoundError检查这些类如果是javax.servlet相关报错说明你的代码或依赖还在用 javaxSpring Boot 3 需要 Jakarta。如果是org.openxmlformats.schemas.wordprocessingml报错可能是 POI 版本和 poi-ooxml-schemas 版本对不上。POI 5.x 不再需要单独引入poi-ooxml-schemas旧版是ooxml-schemas如果历史项目里手动加了旧 schema 依赖删掉新版再试。4.6 Vue 端 a 标签下载无效有的浏览器会拦截动态创建的a点击。解决办法是把link.rel noopener加上或者用window.open兜底但window.open对 blob URL 兼容性一般。更推荐document.body.appendChild之后再 click。如果下载文件名是空字符串浏览器会直接在新标签页打开文件预览而不是下载。所以在getFileName里做兜底确保一定返回一个非空文件名。5. 再进阶一点生成 Markdown 风格的 Word 文档最后分享一个小众但实用的玩法。如果你的业务方不要求复杂的模板格式而是希望把在线编辑的富文本内容比如 Markdown、HTML导出为 Word那就不需要手搓 XWPF 段落了。有一个思路是后端把 Markdown 转成 HTML再交给 Word。但不是所有 Word 都认 HTML。这里有个取巧但有效的方案——用fr.opensagres.xdocreport或者直接用 POI 的XWPFDocument解析 HTML 段落但都比较繁琐。实际上度比较高的做法是前端把 HTML 内容用隐藏的 iframe 打印导出或者使用 html-docx-js 转成 .doc 文件。虽然我在前面说了纯前端方案的局限但对于“在线编辑器里的内容导出成 Word”这个具体场景它有独特优势——能保持排版和图片不丢失。取舍标准就是格式极其严格的合同模板用 poi-tl在线富文本原样导出用前端转换方案。还有一种更现代的流程用 Pandoc 服务批量把 Markdown/HTML 转成 docx。Pandoc 转换质量高支持样式、代码块、表格、目录在服务端可以直接调用命令行适合内容型产品做导出。这个方向如果你有兴趣可以自己搜一下 Pandoc Java 集成的办法我这里就不展开了。6. 实际操作中我总结的几条经验做了这么多导出功能我最大的感受就是导出 Word 这件事80% 的坑不在代码而在格式和环境的约定。第一模板先行。如果你是接受需求的一方拿到需求后别急着写代码先跟业务方把 Word 模板定死。模板里哪些文字是固定不变的哪些地方是动态的表格行数是否可变化图片是固定尺寸还是自适应——这些问题不搞清楚代码写出来大概率要返工。第二前后端联调时先确认响应头。浏览器开发者工具里看 Response Headers确认Content-Type是application/vnd.openxmlformats-officedocument.wordprocessingml.documentContent-Disposition里有正确的文件名。这两个头对了文件能下载就成功了 70%。第三单元测试记得验证文件可打开。后端写完导出接口写个带SpringBootTest的用例直接调用 Service 生成文件到本地临时目录然后用 Word 打开确认格式正确。不要等联调才发现模板样式不对那样排查成本太高。第四导出接口一定要做好超时控制。数据量大或者模板复杂的时候接口响应可能超过 10 秒。前端 axios 的 timeout 要调大Nginx 的 proxy_read_timeout 也要调大否则用户点一次导出等半天没反应体验非常差。第五如果使用 poi-tl版本兼容是重中之重。poi-tl 更新节奏不算快升级 POI 主版本前先看 poi-tl 的 release 说明。我就吃过一次亏POI 升到 5.x 后 poi-tl 1.10.x 直接编译失败后来统一升到 1.12.x 才解决。说实话Spring Boot Vue 导出 Word 本身不是一个高深的技术但它涉及的细节特别多任何一个环节的疏漏都会导致用户拿到一个打不开的文件。希望这篇文章能帮你少走一些弯路。如果你在实际项目中遇到了这里没覆盖到的问题大概率是模板或浏览器兼容性的特殊情况多抓抓响应头多看看文件流内容问题总能定位到。 Spring Boot + Vue 前后端分离导出 Word 文档实战指南
Spring Boot Vue 前后端分离实现导出 Word 文档实战在办公类系统里“导出 Word”绝对是出现频率最高的需求之一。合同、报告、审批单、简历、测试报告业务方经常会说“我要能下载一份正式的 Word 文档格式要能直接编辑”。如果你用的是 Spring Boot Vue 这套前后端分离架构那导出 Word 这件事就有不少细节值得讲清楚——从后端怎么生成真正的 .docx 文件到前端怎么把二进制流完整接住并触发下载中间踩过的坑、走过的弯路我今天一次性理清楚。先说结论基于 Spring Boot 后端生成 Word 文件前端通过接口以二进制流方式下载是目前前后端分离项目里最稳定、最通用的实现路径。这可能和有些同学的直觉不一样——既然 Vue 是前端框架为什么不在前端直接生成 Word我在项目里也试过纯前端方案比如 html-docx-js 这类库小场景确实能用但一旦涉及页码、复杂表格、页眉页脚、服务端模板统一管理前端方案就非常吃力渲染效果也容易跑偏。更关键的是生成文件的逻辑放在后端可以统一处理模板、权限、历史版本换任何前端都能复用同一套接口这才是企业级项目的正确姿势。这篇文章会以一个真实项目为例带你完整走一遍 Spring Boot Vue 导出 Word 的落地过程先讲方案选型背后的考量再拆后端核心实现然后说前端怎么接流最后把高频问题做一个排查手册。无论你是刚接手这类需求的新人还是想优化现有实现的老手这篇都能给你一些可以直接抄作业的东西。1. 整体方案设计与技术选型1.1 为什么选择后端生成 Word 而不是前端生成先聊方案。接到“导出 Word”这个需求第一反应往往不是选技术而是回答一个更根本的问题这份 Word 的内容和格式是固定的还是动态的如果是固定的合同模板、报告模板格式要求严格那模板 占位符替换是首选如果内容完全是动态拼接格式不复杂那可以用代码直接构建文档。在前后端分离架构下我更推荐把生成动作放在后端原因有三个第一模板统一管理。企业的 Word 模板往往需要法务、行政、业务部门反复修改放在后端资源目录里改一次所有用户立即生效。前端生成的话每次模板调整都要发版这是不能接受的。第二数据安全性。导出内容通常涉及业务数据用户有没有权限看这些数据应该由后端校验。数据在服务端生成好了再下发权限问题天然可控。第三跨端一致性。同一个系统可能有 Web 端、管理后台、甚至未来有小程序后端接口一套搞定各端只是触发同一个下载动作而已。1.2 后端生成 docx 的几条技术路线对比确定后端生成之后技术选型又是一个关键节点。我整理一下 Java 生态常见的几种方式方便你做对比。方案特点适用场景Apache POI 原生 API底层、灵活、可控性最强能操作 Word 的段落、表格、图片、样式需要精细控制文档结构且对性能、依赖有一定要求的项目POI 模板占位符替换提前做好 .docx 模板用工具或手写代码替换 ${xxx}格式固定的合同、报告类场景开发效率高poi-tlPOI Template Language基于 POI 封装专为模板引擎设计语法简单功能强大业务模板复杂频繁迭代希望减少样板代码easypoi注解式导出类似 easyexcel支持 Word 导出对格式要求不高追求快速开发的简单导出jacob / comtypes 调用本机 Word需要安装 Office依赖 Windows 环境性能差已经在用 Windows 服务器的老项目私有化部署我的建议是如果只是简单几段文字POI 手搓就够了如果是正经的合同、报告的模板导出直接用 poi-tl 能少写很多代码。后面我会把这两种方式都展开演示。1.3 Spring Boot 版本与依赖引入的踩坑提示这里必须提一个高频坑springboot版本太高。我见过不少项目用 Spring Boot 3.x结果引入 POI 相关依赖时出现ClassNotFoundException或者包冲突原因大多是版本兼容问题。Spring Boot 3.x 基于 Jakarta EE某些旧版本的 POI 工具库内部用了javax命名空间就挂了。安全组合是Spring Boot 2.7.x POI 5.x或者 Spring Boot 3.x POI 5.2.2 以上版本。如果你打算用 poi-tl特别注意 poi-tl 1.12.x 适配 POI 5.x别拿到旧版本 poi-tl 硬配 POI 5.x那会编译都过不去。依赖引入以 Maven 为例核心只要两个dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.5/version /dependency dependency groupIdcom.deepoove/groupId artifactIdpoi-tl/artifactId version1.12.1/version /dependencypoi-tl 自带 POI 依赖理论上加了 poi-tl 就能跑但我习惯显式声明 poi-ooxml 版本避免传递依赖把版本带歪。2. 后端核心实现模板导出与动态生成2.1 基于 poi-tl 的模板占位符方案现在说正事。假如业务方给了一个 docx 模板里面有合同编号、甲方、乙方、签署日期这些字段你只需要在对应位置写上${contractNo}、${partyA}、${partyB}、${signDate}后端拿到数据填充即可。poi-tl 的渲染代码非常简洁import com.deepoove.poi.XWPFTemplate; import com.deepoove.poi.data.Pictures; import java.io.FileOutputStream; import java.io.IOException; import java.util.HashMap; import java.util.Map; public class WordExportService { public void exportContract(String templatePath, String outputPath, String contractNo, String partyA, String partyB) throws IOException { // 1. 准备数据 MapString, Object data new HashMap(); data.put(contractNo, contractNo); data.put(partyA, partyA); data.put(partyB, partyB); data.put(signDate, 2024-06-01); // 2. 渲染模板 XWPFTemplate template XWPFTemplate.compile(templatePath) .render(data); // 3. 写出文件 template.writeToFile(outputPath); template.close(); } }就这么简单。poi-tl 底层仍然是 POI但它把“打开文档 - 查找占位符 - 替换文本/图片/表格 - 保存”这套流程封装好了。你不需要关心 XWPFDocument 的段落遍历、Run 对象的细节。需要说明的是占位符渲染时默认不会继承原占位符的所有样式而是沿用模板里该位置的段落样式。所以模板里多写几行示例文字样式调好再把文字替换成${xxx}最终效果基本是所见即所得。2.2 原生 POI 构建复杂表格设置 Word 表格列宽如果不想引入 poi-tl或者要生成动态行数的表格那原生 POI 是躲不掉的。表格是 Word 导出里最容易翻车的部分而且热搜词里就有“poi设置word表格单元格宽度”和“word 表格列宽无法拖动”可见这个点确实困扰了不少人。用 POI 创建表格的核心代码如下import org.apache.poi.xwpf.usermodel.*; public class TableWordService { public void createReportWithTable(String outputPath) throws Exception { try (XWPFDocument document new XWPFDocument()) { // 1. 创建 2 行 4 列的表格后续可动态插入行 XWPFTable table document.createTable(2, 4); // 2. 设置表格整体宽度单位Twips1 厘米约等于 567 Twips table.setWidth(100%); // 3. 设置每一列的列宽必须先设置 tblLayout 为固定布局否则列宽不生效 table.getCTTbl().getTblPr().setTblLayout( org.openxmlformats.schemas.wordprocessingml.x2006.main.CTTblLayoutType.Factory.newInstance() ); // 表格首行填充数据 XWPFTableRow headerRow table.getRow(0); String[] headers {项目, 数量, 单价, 备注}; for (int i 0; i headers.length; i) { headerRow.getCell(i).setText(headers[i]); // 设置单元格宽度 headerRow.getCell(i).setWidth(2000); } // 4. 动态插入数据行 XWPFTableRow dataRow table.createRow(); dataRow.getCell(0).setText(笔记本电脑); dataRow.getCell(1).setText(2); dataRow.getCell(2).setText(5999); dataRow.getCell(3).setText(固定资产); // 5. 保存 try (java.io.FileOutputStream fos new java.io.FileOutputStream(outputPath)) { document.write(fos); } } } }这里有两个关键坑必须先说列宽不生效直接调getCell(i).setWidth(2000)只在某些 Word 版本里有效。更稳的方式是先设置表格的tblLayout为fixed否则 Word 会根据内容自动调整列宽你设置的数值会被无视。上面代码里已经加了这段。单元格宽度单位POI 的宽度单位是 Twips缇1 英寸 1440 Twips1 厘米约等于 567 Twips。你可能看到很多代码写的是字符串数字比如2000这不是 2000 像素而是 2000 Twips相当于约 3.5 厘米。需要用CTTcPr底层的setTcw来精确设置但大多数场景下setWidth已经够了。2.3 动态行表格生产环境的完整 Service 代码上面只是片段。真实项目中表格行数往往是运行时才知道的比如导出员工列表、订单列表。我习惯这样组织 ServiceService public class ReportExportService { public void exportEmployeeReport(ListEmployee employees, OutputStream outputStream) throws Exception { try (XWPFDocument document new XWPFDocument()) { // 标题 XWPFParagraph title document.createParagraph(); title.setAlignment(ParagraphAlignment.CENTER); XWPFRun titleRun title.createRun(); titleRun.setText(员工信息报告); titleRun.setBold(true); titleRun.setFontSize(18); // 说明段落 XWPFParagraph desc document.createParagraph(); desc.setAlignment(ParagraphAlignment.LEFT); XWPFRun descRun desc.createRun(); descRun.setText(导出时间 LocalDate.now()); descRun.setFontSize(10); // 表格 XWPFTable table document.createTable(employees.size() 1, 4); table.setWidth(100%); // 设置固定布局防止列宽丢失 table.getCTTbl().getTblPr().setTblLayout( org.openxmlformats.schemas.wordprocessingml.x2006.main.CTTblLayoutType.Factory.newInstance() ); // 设置表头 String[] headers {工号, 姓名, 部门, 岗位}; for (int i 0; i headers.length; i) { XWPFTableCell cell table.getRow(0).getCell(i); cell.setText(headers[i]); cell.setWidth(1500); } // 填充数据行 for (int i 0; i employees.size(); i) { Employee emp employees.get(i); XWPFTableRow row table.getRow(i 1); row.getCell(0).setText(emp.getEmployeeNo()); row.getCell(1).setText(emp.getName()); row.getCell(2).setText(emp.getDepartment()); row.getCell(3).setText(emp.getPosition()); } document.write(outputStream); } } }Controller 层直接把这个 OutputStream 对接到 HttpServletResponseRestController RequestMapping(/api/export) public class ExportController { private final ReportExportService exportService; public ExportController(ReportExportService exportService) { this.exportService exportService; } GetMapping(/word/employee) public void exportEmployeeWord(HttpServletResponse response) throws Exception { ListEmployee employees employeeService.listAll(); response.setContentType(application/vnd.openxmlformats-officedocument.wordprocessingml.document); response.setCharacterEncoding(UTF-8); String fileName URLEncoder.encode(员工信息报告_ LocalDate.now() .docx, UTF-8); response.setHeader(Content-Disposition, attachment; filename*UTF-8 fileName); exportService.exportEmployeeReport(employees, response.getOutputStream()); } }这里注意一下Content-Disposition里对文件名做了 URL 编码。这是前端能正确拿到中文文件名的基础后面会再细说。2.4 图片插入带签章或附件的常见写法Word 文档里经常要插入图片比如公司 Logo、签名图片、产品截图。poi-tl 里用Pictures.of()很方便import com.deepoove.poi.data.PictureRenderData; import com.deepoove.poi.data.Pictures; // 模板里写 {{logo}} data.put(logo, Pictures.of(/path/to/logo.png).size(120, 60).create());原生 POI 也不难用XWPFRun.addPicture即可XWPFParagraph paragraph document.createParagraph(); XWPFRun run paragraph.createRun(); try (InputStream is new FileInputStream(/path/to/sign.png)) { run.addPicture(is, XWPFDocument.PICTURE_TYPE_PNG, sign.png, Units.toEMU(80), Units.toEMU(40)); }注意addPicture的宽高单位是 EMU直接用像素不行。POI 提供了Units.toEMU()来做转换。很多同学在这一步图片变形或者不显示基本都是单位没用对或者图片流没有关闭导致文件损坏。3. 前端 Vue 实现文件下载的完整流程3.1 Axios 设置 responseType 和 token后端接口好了前端要接得住这个文件流才行。Vue 项目一般都用 axios最关键的设置有两点responseType: blob告诉 axios 把响应体当二进制流处理而不是默认的 JSON。带上鉴权 header项目里一般有 token 拦截器。看代码import axios from axios export function downloadEmployeeWord(params) { return axios({ url: /api/export/word/employee, method: get, params, responseType: blob, // 核心必须以 blob 形式接收 timeout: 30000 // 导出可能较慢给足时间 }) }如果你的 axios 实例统一在拦截器里加 token那这里不需要重复处理。但一定要确认拦截器没有对 blob 做 JSON 解析。我踩过一次坑响应拦截器里统一做了response.data JSON.parse(response.data)结果导出 Word 时直接报错因为二进制流转 JSON 必挂。后来在拦截器里加了一个判断service.interceptors.response.use( (response) { // 判断是否为二进制流 if (response.data instanceof Blob) { return response } // 其他逻辑 return response.data }, (error) { return Promise.reject(error) } )这个判断很关键。因为后端出错时返回的往往不是 Blob而是 JSON 错误信息前端需要区分这两种情况避免把错误信息当文件下载下来。3.2 Blob 下载与文件名中文乱码处理拿到response后需要把它转成下载动作。最关键的就是从Content-Disposition响应头里解析文件名。function getFileName(disposition) { if (!disposition) return 导出文件.docx // 从 filename*UTF-8xxx 中提取 let result disposition.match(/filename\*UTF-8([^;])/i) if (result result[1]) { try { return decodeURIComponent(result[1]) } catch (e) { return 导出文件.docx } } // 兼容 filenamexxx.docx 的旧写法 result disposition.match(/filename?([^]*)?/i) return result ? result[1] : 导出文件.docx } export async function handleDownloadEmployeeWord(params) { try { const response await downloadEmployeeWord(params) // 服务端返回错误时是 JSON需要先判断 if (response.data.type application/json) { const reader new FileReader() reader.onload () { const errorData JSON.parse(reader.result) Message.error(errorData.message || 导出失败) } reader.readAsText(response.data) return } const blob new Blob([response.data], { type: application/vnd.openxmlformats-officedocument.wordprocessingml.document }) const fileName getFileName(response.headers[content-disposition]) const link document.createElement(a) link.href URL.createObjectURL(blob) link.download fileName document.body.appendChild(link) link.click() document.body.removeChild(link) URL.revokeObjectURL(link.href) } catch (error) { Message.error(导出失败请稍后重试) } }代码不算复杂但有三个细节值得展开第一filename*和filename的区别。后端设置了filename*UTF-8xxx这表示经过 URL 编码的文件名中文能正常传输。如果后端只写了filename员工信息报告.docx那是 ISO-8859-1 编码中文在 HTTP 头里会乱码前端拿到就是一堆问号。所以前后端配合时必须统一用filename*。第二blob.type 要设置对。不设置虽然也能下载但文件类型标识不对可能导致 Word 打开时提示文件损坏或格式不兼容。docx 对应的 MIME 类型是application/vnd.openxmlformats-officedocument.wordprocessingml.document这个字符串很容易记错我每次都是直接复制。第三创建a标签后要手动 append 到 body 再 click最后移除。这是为了兼容 Firefox 老版本。现代浏览器不加也能用但加上最稳。3.3 部署环境中的额外注意事项前端部署后如果用的是 Nginx还需要注意代理配置。/api路径要正确代理到后端服务并且proxy_buffering需要开启默认就是开着的否则大文件下载可能被截断。另外如果你发现下载的文件打不开、提示“文件已损坏”先别急着怀疑代码先看文件大小。后端导出的 docx 如果只有 1KB 不到大概率是返回了 JSON 错误信息只是它被保存成了 .docx 后缀。这时候用文本编辑器打开那个文件看看内容是不是{code:500,message:...}这是最直接的排查方式。4. 常见问题与排查技巧实录4.1 文件损坏或打不开这是导出 Word 类需求最高频的报错。可能的原因有很多我按排查优先级列一下症状可能原因解决办法文件只有 1KB用文本打开是 JSON后端异常被前端存成 docx前端判断response.data.type application/json显示错误信息文件大小正常但打开报错模板本身损坏用 Word 打开原模板另存为新的 docx 再试试文件下载中途断开后端没有及时 flush OutputStream或超时设置太短Service 里document.write(outputStream)后立即flush()调大 axios timeout打开时提示“权限”或“内容错误”代码里关闭流时把文档写坏了检查是否在try-with-resources管理 XWPFDocument避免重复关闭这里特别提醒一个点HSSF/XWPF 系列导出 Word 时document.write(outputStream)之后不要再对 response 做任何 setContentType 二次设置否则会破坏已经写好的响应头导致文件内容不完整。我遇到过一次Controller 方法里有个CrossOrigin注解配合过滤器又写了一次响应头文件就坏了。4.2 中文文件名乱码文件名乱码基本是 Content-Disposition 头的问题。我习惯在后端统一这样设置String fileName URLEncoder.encode(员工信息报告.docx, UTF-8); response.setHeader(Content-Disposition, attachment; filename\ fileName \; filename*UTF-8 fileName);filename给一个 ASCII 转义版本URL 编码后的字符串filename*给标准 RFC 5987 格式。这样老浏览器也能解析现代浏览器优先用filename*中文就不会乱。4.3 Word 表格列宽无法拖动/设置不生效表格列宽是另一个重灾区。我在 2.2 里已经给了核心代码这里再说一个常见场景模板里的表格列宽在 Word 里无法拖动。这往往是因为模板本身设置了“固定列宽” 自动调整被禁用。处理方式是在模板阶段就把表格布局设置为“自动调整”或者在 POI 里显式设置列宽。如果用 poi-tl 渲染表格并希望列宽固定可以给表格的每一列设置gridSpan或tcW。poi-tl 官方文档里提到可以用Configure来自定义表格策略但大多数情况下原生 POI 的setWidth已经足够。4.4 Word 关闭时卡顿和导出代码有没有关系热搜词里有一条“word关闭时卡顿”很多同学担心是自己导出的文件有问题。说实话这个概率很低。Word 关闭卡顿通常是本机软件问题比如加载项、缓存问题。但有一种情况和你导出的文件有关文件里嵌入了大量高清图片且未压缩文档体积达到几十 MB。打开这样的文档Word 内存占用高关闭时卡顿是正常的。如果你导出报告包含图片建议在插入前先压缩图片尺寸或者在插入时限制图片显示大小。POI 中Pictures.of().size(width, height)只控制显示尺寸原始图片体积不变所以尽量在源头控制图片文件大小。4.5 Spring Boot 版本太高引发的依赖问题Spring Boot 3.x 用户如果遇到 POI 相关NoClassDefFoundError检查这些类如果是javax.servlet相关报错说明你的代码或依赖还在用 javaxSpring Boot 3 需要 Jakarta。如果是org.openxmlformats.schemas.wordprocessingml报错可能是 POI 版本和 poi-ooxml-schemas 版本对不上。POI 5.x 不再需要单独引入poi-ooxml-schemas旧版是ooxml-schemas如果历史项目里手动加了旧 schema 依赖删掉新版再试。4.6 Vue 端 a 标签下载无效有的浏览器会拦截动态创建的a点击。解决办法是把link.rel noopener加上或者用window.open兜底但window.open对 blob URL 兼容性一般。更推荐document.body.appendChild之后再 click。如果下载文件名是空字符串浏览器会直接在新标签页打开文件预览而不是下载。所以在getFileName里做兜底确保一定返回一个非空文件名。5. 再进阶一点生成 Markdown 风格的 Word 文档最后分享一个小众但实用的玩法。如果你的业务方不要求复杂的模板格式而是希望把在线编辑的富文本内容比如 Markdown、HTML导出为 Word那就不需要手搓 XWPF 段落了。有一个思路是后端把 Markdown 转成 HTML再交给 Word。但不是所有 Word 都认 HTML。这里有个取巧但有效的方案——用fr.opensagres.xdocreport或者直接用 POI 的XWPFDocument解析 HTML 段落但都比较繁琐。实际上度比较高的做法是前端把 HTML 内容用隐藏的 iframe 打印导出或者使用 html-docx-js 转成 .doc 文件。虽然我在前面说了纯前端方案的局限但对于“在线编辑器里的内容导出成 Word”这个具体场景它有独特优势——能保持排版和图片不丢失。取舍标准就是格式极其严格的合同模板用 poi-tl在线富文本原样导出用前端转换方案。还有一种更现代的流程用 Pandoc 服务批量把 Markdown/HTML 转成 docx。Pandoc 转换质量高支持样式、代码块、表格、目录在服务端可以直接调用命令行适合内容型产品做导出。这个方向如果你有兴趣可以自己搜一下 Pandoc Java 集成的办法我这里就不展开了。6. 实际操作中我总结的几条经验做了这么多导出功能我最大的感受就是导出 Word 这件事80% 的坑不在代码而在格式和环境的约定。第一模板先行。如果你是接受需求的一方拿到需求后别急着写代码先跟业务方把 Word 模板定死。模板里哪些文字是固定不变的哪些地方是动态的表格行数是否可变化图片是固定尺寸还是自适应——这些问题不搞清楚代码写出来大概率要返工。第二前后端联调时先确认响应头。浏览器开发者工具里看 Response Headers确认Content-Type是application/vnd.openxmlformats-officedocument.wordprocessingml.documentContent-Disposition里有正确的文件名。这两个头对了文件能下载就成功了 70%。第三单元测试记得验证文件可打开。后端写完导出接口写个带SpringBootTest的用例直接调用 Service 生成文件到本地临时目录然后用 Word 打开确认格式正确。不要等联调才发现模板样式不对那样排查成本太高。第四导出接口一定要做好超时控制。数据量大或者模板复杂的时候接口响应可能超过 10 秒。前端 axios 的 timeout 要调大Nginx 的 proxy_read_timeout 也要调大否则用户点一次导出等半天没反应体验非常差。第五如果使用 poi-tl版本兼容是重中之重。poi-tl 更新节奏不算快升级 POI 主版本前先看 poi-tl 的 release 说明。我就吃过一次亏POI 升到 5.x 后 poi-tl 1.10.x 直接编译失败后来统一升到 1.12.x 才解决。说实话Spring Boot Vue 导出 Word 本身不是一个高深的技术但它涉及的细节特别多任何一个环节的疏漏都会导致用户拿到一个打不开的文件。希望这篇文章能帮你少走一些弯路。如果你在实际项目中遇到了这里没覆盖到的问题大概率是模板或浏览器兼容性的特殊情况多抓抓响应头多看看文件流内容问题总能定位到。