简介在Java服务端开发中将doc、xls等格式转为PDF并在线预览是一项常见需求。这套基于Apache POI与iTextPDF的Java实现面向需要处理文档转换与在线预览功能的后端开发者可解决旧版xls、新版xlsx及doc、txt、图片等多格式统一转PDF的问题。资源包共6个文件其中5个Java源码文件覆盖Word转PDF、Excel转PDF、文件浏览、HTML转换及中文字体支持等核心工具类另附1个txt说明文件用于整理依赖jar包版本压缩包仅7KB轻量易读。目前已有2388人学习下载。通过阅读源码可以掌握HSSF/XSSF读取与写入Excel、iTextPDF创建PDF并插入文字/表格/图片、字体与样式设置以及结合Java Web上传转换、前端预览的整体实现思路工具类拆分清晰便于直接改造成Spring MVC或Servlet项目中的转换服务适合正在搭建在线文档预览功能的初中级Java开发者参考借鉴。 换个姿势说需求——场景永远是“客户有一个doc/xls要传到网页上直接看还不能下载原文件”。做过企业OA、合同管理、知识库这类系统的朋友应该都有印象这个需求几乎和“用户管理”一样高频。标题里的“java实现doc、xls等格式转换pdf实现在线浏览”一句话拆开其实是两个独立但强关联的问题第一服务端怎么把Office文档转成PDF第二浏览器端怎么把这个PDF呈现给用户且不暴露原文件。这篇文章我按自己的实践路径来写不是单纯堆方案而是把选型逻辑、核心代码、线上踩坑一起讲清楚。项目背景是某内部文档管理系统要求在浏览器里预览doc、docx、xls、xlsx、ppt、pptx等Office文件原文件不允许下载。整体做下来核心选型是LibreOffice headless加JODConverter配合PDF.js做前端展示。适合正在做同类功能、或者准备做但还没定技术方案的Java开发参考。1. 方案选型为什么最后选了LibreOffice JODConverter先说结论Java生态里做Office转PDF主流路线就那么几条我全试过一遍。第一类是纯Java解析库比如Apache POI配合iText或PDFBox自己拼PDF。这个方案最大的问题是工作量不可控。POI能读doc和xls的内容但Office文档的排版模型极其复杂doc的流式布局、xls的打印区域、合并单元格、页眉页脚这些要在PDF里原样还原等于自己实现一个排版引擎。做出来能用但任何一个复杂文档都能让你改一个月。第二类是商业组件比如Aspose.Words和Aspose.Cells。效果确实好转换保真度高API设计也简单转出来的PDF几乎和Office打开再另存为的效果一样。但价格不便宜而且商用授权有严格限制企业内部部署还好说给客户做交付的时候授权问题会变成一个谈判点。审计风险也比较麻烦不是所有项目都愿意背着这个成本。第三类就是借助操作系统里的Office软件。Windows上可以调用COM接口操作本机Office但这个方案要求服务器装Office且带桌面环境并发一高就出各种莫名其妙的问题容器化部署基本没法做。更通用的做法是装LibreOffice或者OpenOffice通过命令行或者JODConverter以headless模式运行把Office文档转成PDF。我最终选了LibreOffice JODConverter理由很务实免费开源无授权风险LibreOffice是LGPL协议集成进商业系统完全没问题容器化友好Linux服务器上装个libreoffice-core就能跑不需要图形界面转换保真度可接受对常规办公文档的排版支持已经很成熟比起OpenOfficeLibreOffice的兼容性更好JODConverter封装得比较完善管理LibreOffice进程生命周期不用自己裸调命令行当然这个方案也有短板后面会讲比如中文字体问题、并发效率问题。但整体上在“免费、可控、效果达标”这三个约束下这是最均衡的选择。1.1 几种方案的横向对比方案转换质量开发成本授权成本并发能力部署复杂度POI PDFBox 手写低极高无高低Aspose 系列高低高高低OpenOffice JODConverter中低无中中LibreOffice JODConverter中高低无中中调用本机 Office COM高中需购买Office极低高仅限Windows提示如果你的项目预算充足、对转换质量有硬性要求比如法律合同、设计稿可以直接考虑Aspose省心。其余大多数内部系统场景LibreOffice方案已经足够。2. 环境搭建与核心代码实现这一节是实操部分。我用的是Spring Boot项目JDK 1.8服务器是CentOS 7LibreOffice版本是7.3。整体流程不复杂但有几个细节不处理好会反复踩坑。2.1 Linux服务器上安装LibreOfficeCentOS上安装很简单# 安装 LibreOffice 无界面版本只装核心组件即可 yum install -y libreoffice-core libreoffice-writer libreoffice-calc libreoffice-impress # 安装中文字体重点后面会讲为什么 yum install -y fontconfig fc-cache -f安装完成后验证一下libreoffice --version能输出版本号就说明装好了。如果只装core还不够writer对应doc/docxcalc对应xls/xlsximpress对应ppt/pptx按需安装。2.2 JODConverter的引入和配置JODConverter有新旧两个版本。老版本是org.jodconverter:jodconverter核心类叫OfficeDocumentConverter。新版本改成了org.jodconverter:jodconverter-local包名和API都变了。我用的新版本maven坐标dependency groupIdorg.jodconverter/groupId artifactIdjodconverter-local/artifactId version4.4.6/version /dependency注意JODConverter本身不包含LibreOffice它只是帮你管理LibreOffice进程。所以LibreOffice还是要单独装。它的工作原理是启动一个LibreOffice进程监听指定端口JODConverter通过socket把转换任务交给它转换完成后返回结果。提示端口冲突是初学者经常遇到的问题。LibreOffice默认端口是2002如果你的服务器上已经有别的服务占用了要用officeManager的portNumber属性改掉。配置一个OfficeManager的Bean这是JODConverter的核心入口Configuration public class OfficeConvertConfig { Bean public OfficeManager officeManager() { OfficeManager officeManager LocalOfficeManager.builder() .install() .portNumbers(2002, 2003) .taskQueueTimeout(60000) .taskExecutionTimeout(30000) .build(); officeManager.start(); return officeManager; } }这里有几个参数值得解释一下portNumbersLibreOffice进程监听的端口可以配多个JODConverter会自动做负载均衡。一次只能有一个LibreOffice进程连接一个端口所以并发量上来了多端口能提升吞吐。taskQueueTimeout任务在队列里等待的最长时间。如果超过这个时间还在排队直接抛异常。默认30秒我调大到60秒因为有些大的Excel文件转换本身就要几十秒。taskExecutionTimeout单个任务转换的超时时间。这个要看业务普通doc文件几秒钟就完成但一个几十MB、带复杂公式的xlsx可能要十几秒甚至更久。我设成30秒还是有超高概率超时的后面在问题排查里会说怎么优化。2.3 转换服务的核心实现配置好OfficeManager之后转换逻辑本身很简单Component public class OfficeToPdfService { private final OfficeManager officeManager; public OfficeToPdfService(OfficeManager officeManager) { this.officeManager officeManager; } public File convertToPdf(File inputFile) { File outputFile null; try { outputFile File.createTempFile(converted, .pdf); LocalConverter.builder() .officeManager(officeManager) .build() .convert(inputFile) .to(outputFile) .execute(); return outputFile; } catch (OfficeException e) { throw new RuntimeException(文件转换失败, e); } finally { // 调用方负责清理临时文件这里不删除方便排查问题 } } }JODConverter 4.x的API是链式调用.convert()接收输入文件.to()指定输出文件.execute()执行转换。就这么简单。但如果你以为这就完了那就太天真了。真实业务里文件不是本地路径而是上传到服务器的字节流。所以更通用的做法是把InputStream转成临时文件再转换public byte[] convertToPdf(InputStream inputStream, String originalFileName) { File tempInput null; File tempOutput null; try { // 根据原始文件后缀创建临时输入文件 String suffix getSuffix(originalFileName); tempInput File.createTempFile(input, suffix); FileCopyUtils.copy(inputStream, tempInput); tempOutput File.createTempFile(output, .pdf); LocalConverter.builder() .officeManager(officeManager) .build() .convert(tempInput) .to(tempOutput) .execute(); return FileCopyUtils.copyToByteArray(tempOutput); } catch (Exception e) { throw new RuntimeException(文件转换失败, e); } finally { // 一定记得删除临时文件不然磁盘会被慢慢吃完 if (tempInput ! null) { tempInput.delete(); } if (tempOutput ! null) { tempOutput.delete(); } } }这里有一个非常重要的细节临时输入文件一定要用原始文件的后缀。为什么LibreOffice判断文件类型不是靠文件内容而是靠扩展名。你把一个docx内容保存成input.tmpLibreOffice会把它当成未知类型转换直接失败或者转出乱码。这个坑我第一次踩的时候排查了半天。3. 在线浏览的实现PDF如何优雅地展示在网页上文件转成PDF之后剩下的问题就是怎么在浏览器里展示了。这里有几个方案我按实际使用体验排个序最省事的方式是直接把PDF文件的URL放在浏览器地址栏或者用iframe/object/embed标签嵌入。现代浏览器Chrome、Firefox、Edge、Safari都内置了PDF查看器打开就是原生预览支持翻页、缩放、搜索。代码就一行iframe src/preview/123.pdf stylewidth: 100%; height: 800px;/iframe为什么推荐PDF.js原因有几个第一浏览器兼容性不统一。同样的PDFChrome打开没问题但某些老旧内核的浏览器比如企业里还大量存在的IE内核、360兼容模式是没有内置PDF查看器的打开就是一坨乱码或者直接变下载。第二无法控制交互行为。原生查看器右键就有“另存为”对“不允许下载原文件”这种需求完全没法控制。虽然PDF转换后已经是另一份文件但用户仍然可以把PDF下载走。如果业务要求是“只能看不能拿”还得在此基础上做权限控制比如加水印、禁止打印、分页渲染成图片。第三UI不可定制。项目方经常要求“预览界面和我们系统的风格一致”原生查看器做不到。PDF.js是Mozilla开源的JavaScript库它在网页里自己渲染PDF不依赖浏览器内置能力。核心用法分两步第一步引入pdf.js库script src/static/pdfjs/pdf.min.js/script第二步把PDF字节流交给pdf.js去渲染这里有一个重要的注意点。pdf.js通常有两种加载PDF的方式传PDF文件的URL或者传一个Uint8Array。考虑到文件权限控制更推荐后端返回字节流前端用ArrayBuffer方式加载这样用户拿不到PDF的真实URL也方便做权限拦截async function previewPdf(fileUrl) { const response await fetch(fileUrl); const arrayBuffer await response.arrayBuffer(); const pdf await pdfjsLib.getDocument({ data: arrayBuffer }).promise; const page await pdf.getPage(1); const scale 1.5; const viewport page.getViewport({ scale }); const canvas document.getElementById(pdf-canvas); const context canvas.getContext(2d); canvas.width viewport.width; canvas.height viewport.height; await page.render({ canvasContext: context, viewport, task: new pdfjsLib.RenderTask() }).promise; }上面的代码只渲染了第一页完整版需要写一个循环把所有页都渲染出来。这里让我踩坑的是RenderTask()的用法。如果页面渲染到一半用户翻页或者关闭不取消renderTask的话后台会一直执行渲染内存悄悄涨。所以多页渲染时要维护一个当前渲染任务的引用翻页时先执行renderTask.cancel()再渲染新页面。3.1 PDF.js访问控制的关键点前面提到“不能下载原文件”这个需求做权限控制时有两个层面接口层面预览接口要校验用户登录态和权限不能是公开URL。代码结构上应该是这样RestController RequestMapping(/preview) public class PreviewController { GetMapping(/{fileId}) public ResponseEntitybyte[] preview(PathVariable String fileId, RequestHeader(Authorization) String token) { // 1. 校验token确认用户登录 // 2. 校验用户对该文件的访问权限 // 3. 从文件服务或数据库读取原文件 // 4. 转成PDF // 5. 返回Content-Type: application/pdf } }另外一个安全细节是千万不要把一个永久有效的静态URL暴露给前端。比较稳妥的做法是用一个带过期时间的临时token拼在URL里比如/preview/{fileId}?tokenxxxexpiresxxx后端校验token和过期时间都通过了才返回PDF内容。这样即使URL泄露一段时间后也失效了不会变成永久后门。3.2 转图片展示的备选方案如果你的业务对安全性要求特别高PDF都不能让用户直接拿到完整文件那还有一个方案把PDF逐页转成图片前端只展示图片用户无法获得原始PDF文件。实现思路有两种一种是用PDFBox逐页渲染。Apache PDFBox自带PDF渲染能力PDDocument document PDDocument.load(pdfFile); PDFRenderer renderer new PDFRenderer(document); for (int i 0; i document.getNumberOfPages(); i) { BufferedImage image renderer.renderImageWithDPI(i, 150); ImageIO.write(image, png, new File(outputDir /page_ i .png)); }另一种是转成SVG用SVG做前端展示缩放不失真且可以选中文字但实现复杂度更高。一般图片方案就够用了。这个方案的代价是文件体积膨胀。一页A4纸150DPI的PNG大概一两百KB一个50页的PDF转成图片后体积大约是原始PDF的5到10倍。如果文档量大的话磁盘和带宽压力会上升。4. 常见问题排查与避坑实录整个项目做下来真正耗时间的不是写代码而是解决各种环境问题和边缘case。这里把线上实际遇到的问题整理了几个按出现频率排序。4.1 转换出来的PDF中文全是方块、乱码这个问题几乎人人都能遇到。原因很简单Linux服务器上没有安装中文字体LibreOffice找不到能渲染中文的字体于是用默认字体替换结果替换的字体也不支持中文就变成了方块。排查方法# 查看系统已安装的中文字体 fc-list :langzh如果输出为空说明一个中文字体都没有。解决方法就是安装中文字体最省事的是装fonts-wqy-zenhei或者fonts-wqy-microhei文泉驿正黑和文泉驿微米黑yum install -y fonts-wqy-zenhei fonts-wqy-microhei fc-cache -f提示如果项目涉及合同、公文这类对字形有严格要求的场景建议直接把Windows下的宋体、黑体、仿宋、楷体字体文件simsun.ttc、simhei.ttf、simfang.ttf、simkai.ttf上传到/usr/share/fonts/目录再执行fc-cache -f。项目里的正式文档用宋体排版的情况很多客户看到默认字体变成文泉驿会提意见的。还有一个进阶问题。即使装了字体LibreOffice对docx中“微软雅黑”这类字体的映射也可能不正确因为LibreOffice并没有微软雅黑这个字体它只能用一个近似字体替代。这个问题需要在LibreOffice的字体映射表里手动配置替代规则或者确保文档里用的都是服务器上存在的字体。4.2 转换任务偶尔超时失败系统上线初期用户反馈文档多的时候经常转换失败。排查下来主要原因是并发量超出LibreOffice的处理能力。JODConverter的默认配置里一个OfficeManager管理一个LibreOffice进程一次只能处理一个转换任务。其他任务都在队列里排队。如果单个转换本身就耗时几十秒队列堆积很快后面的任务直接超时。优化的几个方向多端口并行配置多个端口创建多个LibreOffice进程JODConverter会自动分散任务调整超时时间根据实际转换耗时合理设置taskQueueTimeout和taskExecutionTimeout加一层缓存对同一个文件重复转换的场景比如用户反复打开预览可以把转换结果缓存起来。最粗暴的做法是在内存里放一个Mapkey是文件内容的MD5value是转换后的PDF字节流。正式一点用Redis存小文件、磁盘存大文件4.3 加密文档和损坏文档转换报错这个属于典型的输入数据异常。LibreOffice对加密的Office文档转换时会直接拒绝或输出乱码。损坏的docx文件比如zip结构被破坏也会导致转换失败。处理策略是转换前先做文件校验。对于docx/xlsx这类基于OOXML格式的文件本质是个zip包可以尝试用Java的ZipFile打开能正常读取就说明文件结构基本完整。加密文档的判断简单些比如docx的/word/document.xml如果内容是加密的二进制那解压后看不到明文XML结构也算一种判断手段。对这种异常文件业务侧的处理是返回友好的错误提示而不是抛500让用户看到一堆堆栈。在controller层加个全局异常拦截转换失败统一提示“文件格式不正确或已损坏请重新上传”。4.4 临时文件堆积导致磁盘爆满这是个不起眼但是非常致命的问题。转换流程里创建了很多临时文件如果代码里没有正确清理或者进程在转换过程中被kill掉临时文件就会残留在/tmp目录里。线上跑几个月后一个40GB的磁盘可能就被吃光了。解决方式有三道防线第一道代码里在finally块中删除自己创建的临时文件。第二道配置系统定时任务定期清理/tmp下的残留文件# crontab 每天凌晨3点清理 3 天前的转换临时文件 0 3 * * * find /tmp -name input* -mtime 3 -delete; find /tmp -name output* -mtime 3 -delete第三道把临时文件目录从系统盘切到单独的数据盘分区的/tmp/office_convert避免影响系统的其他部分。4.5 大Excel文件转换内存溢出一个20MB的xlsx带大量公式和条件格式LibreOffice转换时内存占用可能超过512MB。这个在容器化部署时特别容易踩。JVM内存和LibreOffice进程内存是分开算的但容器总内存是有限制的。如果部署时只给容器3GBJVM配了2GBLibreOffice再吃1GB就可能OOM。这里有三个层面的优化思路第一层把LibreOffice的可执行文件路径配置成它自己的配置限制其内存使用。可以在JODConverter的配置里指定templateProfileDir或者直接修改LibreOffice的启动参数。第二层上传时就限制文件大小。业务上千方百计想把“能转的文件”范围扩大但性能实测下来超过100MB的xlsx转换时间就很不可控了直接在上传接口做拦截更实际。第三层大文件转换走异步任务。前端先展示“转换中”状态转换完成后通过WebSocket或者轮询通知前端预览。这个体验比同步等待超时好得多也是目前在线预览系统的常规做法。异步架构下同步接口返回的不再是PDF字节流而是一个任务ID。5. 几点复盘建议项目上线后我复盘了一遍有几个体会比较深分享给要做类似功能的同学第一先把文件类型边界定义清楚。不是所有的Office文档都能完美转PDF。比如visio的vsdx文件LibreOffice根本打不开邮件格式的msg转出来效果可能很糟糕。这些边缘格式要提前和业务方对齐明确支持范围不要在项目验收阶段才讨论“为什么这个文件打不开”。第二转换质量要用真实业务文档验证。拿三个从网上下载的模板测试根本不够一定要让业务方提供实际使用的文档类型特别是他们最复杂的几个。比如人事部有几十个自动化表格宏的xlsm转出来可能和Excel里看到的完全不一样。提前暴露问题比上线后处理投诉成本低得多。第三在线预览和在线编辑是两码事。很多业务方口中的“在线浏览”语义其实很模糊有人想要的就是“看个大概”有人想要的是“所见即所得我能复制文字筛选表格”。PDF方案能满足“看”和“复制文字”这类需求但“在线编辑后保存回原格式”是完全不同的技术栈需要OnlyOffice或Collabora这类协作编辑套件。这个边界在需求澄清阶段一定要问清楚不然技术选型会跑偏。最终回头看这个功能的价值在于把用户从“下载文件 - 安装Office - 打开看 - 再关掉”的链条中解放出来直接在网页里完成阅读和轻量操作。技术本身不酷但实打实地解决了用户每天都要重复的痛事。本文还有配套的精品资源点击获取
Java实现Office文档转PDF在线浏览的完整实践方案
简介在Java服务端开发中将doc、xls等格式转为PDF并在线预览是一项常见需求。这套基于Apache POI与iTextPDF的Java实现面向需要处理文档转换与在线预览功能的后端开发者可解决旧版xls、新版xlsx及doc、txt、图片等多格式统一转PDF的问题。资源包共6个文件其中5个Java源码文件覆盖Word转PDF、Excel转PDF、文件浏览、HTML转换及中文字体支持等核心工具类另附1个txt说明文件用于整理依赖jar包版本压缩包仅7KB轻量易读。目前已有2388人学习下载。通过阅读源码可以掌握HSSF/XSSF读取与写入Excel、iTextPDF创建PDF并插入文字/表格/图片、字体与样式设置以及结合Java Web上传转换、前端预览的整体实现思路工具类拆分清晰便于直接改造成Spring MVC或Servlet项目中的转换服务适合正在搭建在线文档预览功能的初中级Java开发者参考借鉴。 换个姿势说需求——场景永远是“客户有一个doc/xls要传到网页上直接看还不能下载原文件”。做过企业OA、合同管理、知识库这类系统的朋友应该都有印象这个需求几乎和“用户管理”一样高频。标题里的“java实现doc、xls等格式转换pdf实现在线浏览”一句话拆开其实是两个独立但强关联的问题第一服务端怎么把Office文档转成PDF第二浏览器端怎么把这个PDF呈现给用户且不暴露原文件。这篇文章我按自己的实践路径来写不是单纯堆方案而是把选型逻辑、核心代码、线上踩坑一起讲清楚。项目背景是某内部文档管理系统要求在浏览器里预览doc、docx、xls、xlsx、ppt、pptx等Office文件原文件不允许下载。整体做下来核心选型是LibreOffice headless加JODConverter配合PDF.js做前端展示。适合正在做同类功能、或者准备做但还没定技术方案的Java开发参考。1. 方案选型为什么最后选了LibreOffice JODConverter先说结论Java生态里做Office转PDF主流路线就那么几条我全试过一遍。第一类是纯Java解析库比如Apache POI配合iText或PDFBox自己拼PDF。这个方案最大的问题是工作量不可控。POI能读doc和xls的内容但Office文档的排版模型极其复杂doc的流式布局、xls的打印区域、合并单元格、页眉页脚这些要在PDF里原样还原等于自己实现一个排版引擎。做出来能用但任何一个复杂文档都能让你改一个月。第二类是商业组件比如Aspose.Words和Aspose.Cells。效果确实好转换保真度高API设计也简单转出来的PDF几乎和Office打开再另存为的效果一样。但价格不便宜而且商用授权有严格限制企业内部部署还好说给客户做交付的时候授权问题会变成一个谈判点。审计风险也比较麻烦不是所有项目都愿意背着这个成本。第三类就是借助操作系统里的Office软件。Windows上可以调用COM接口操作本机Office但这个方案要求服务器装Office且带桌面环境并发一高就出各种莫名其妙的问题容器化部署基本没法做。更通用的做法是装LibreOffice或者OpenOffice通过命令行或者JODConverter以headless模式运行把Office文档转成PDF。我最终选了LibreOffice JODConverter理由很务实免费开源无授权风险LibreOffice是LGPL协议集成进商业系统完全没问题容器化友好Linux服务器上装个libreoffice-core就能跑不需要图形界面转换保真度可接受对常规办公文档的排版支持已经很成熟比起OpenOfficeLibreOffice的兼容性更好JODConverter封装得比较完善管理LibreOffice进程生命周期不用自己裸调命令行当然这个方案也有短板后面会讲比如中文字体问题、并发效率问题。但整体上在“免费、可控、效果达标”这三个约束下这是最均衡的选择。1.1 几种方案的横向对比方案转换质量开发成本授权成本并发能力部署复杂度POI PDFBox 手写低极高无高低Aspose 系列高低高高低OpenOffice JODConverter中低无中中LibreOffice JODConverter中高低无中中调用本机 Office COM高中需购买Office极低高仅限Windows提示如果你的项目预算充足、对转换质量有硬性要求比如法律合同、设计稿可以直接考虑Aspose省心。其余大多数内部系统场景LibreOffice方案已经足够。2. 环境搭建与核心代码实现这一节是实操部分。我用的是Spring Boot项目JDK 1.8服务器是CentOS 7LibreOffice版本是7.3。整体流程不复杂但有几个细节不处理好会反复踩坑。2.1 Linux服务器上安装LibreOfficeCentOS上安装很简单# 安装 LibreOffice 无界面版本只装核心组件即可 yum install -y libreoffice-core libreoffice-writer libreoffice-calc libreoffice-impress # 安装中文字体重点后面会讲为什么 yum install -y fontconfig fc-cache -f安装完成后验证一下libreoffice --version能输出版本号就说明装好了。如果只装core还不够writer对应doc/docxcalc对应xls/xlsximpress对应ppt/pptx按需安装。2.2 JODConverter的引入和配置JODConverter有新旧两个版本。老版本是org.jodconverter:jodconverter核心类叫OfficeDocumentConverter。新版本改成了org.jodconverter:jodconverter-local包名和API都变了。我用的新版本maven坐标dependency groupIdorg.jodconverter/groupId artifactIdjodconverter-local/artifactId version4.4.6/version /dependency注意JODConverter本身不包含LibreOffice它只是帮你管理LibreOffice进程。所以LibreOffice还是要单独装。它的工作原理是启动一个LibreOffice进程监听指定端口JODConverter通过socket把转换任务交给它转换完成后返回结果。提示端口冲突是初学者经常遇到的问题。LibreOffice默认端口是2002如果你的服务器上已经有别的服务占用了要用officeManager的portNumber属性改掉。配置一个OfficeManager的Bean这是JODConverter的核心入口Configuration public class OfficeConvertConfig { Bean public OfficeManager officeManager() { OfficeManager officeManager LocalOfficeManager.builder() .install() .portNumbers(2002, 2003) .taskQueueTimeout(60000) .taskExecutionTimeout(30000) .build(); officeManager.start(); return officeManager; } }这里有几个参数值得解释一下portNumbersLibreOffice进程监听的端口可以配多个JODConverter会自动做负载均衡。一次只能有一个LibreOffice进程连接一个端口所以并发量上来了多端口能提升吞吐。taskQueueTimeout任务在队列里等待的最长时间。如果超过这个时间还在排队直接抛异常。默认30秒我调大到60秒因为有些大的Excel文件转换本身就要几十秒。taskExecutionTimeout单个任务转换的超时时间。这个要看业务普通doc文件几秒钟就完成但一个几十MB、带复杂公式的xlsx可能要十几秒甚至更久。我设成30秒还是有超高概率超时的后面在问题排查里会说怎么优化。2.3 转换服务的核心实现配置好OfficeManager之后转换逻辑本身很简单Component public class OfficeToPdfService { private final OfficeManager officeManager; public OfficeToPdfService(OfficeManager officeManager) { this.officeManager officeManager; } public File convertToPdf(File inputFile) { File outputFile null; try { outputFile File.createTempFile(converted, .pdf); LocalConverter.builder() .officeManager(officeManager) .build() .convert(inputFile) .to(outputFile) .execute(); return outputFile; } catch (OfficeException e) { throw new RuntimeException(文件转换失败, e); } finally { // 调用方负责清理临时文件这里不删除方便排查问题 } } }JODConverter 4.x的API是链式调用.convert()接收输入文件.to()指定输出文件.execute()执行转换。就这么简单。但如果你以为这就完了那就太天真了。真实业务里文件不是本地路径而是上传到服务器的字节流。所以更通用的做法是把InputStream转成临时文件再转换public byte[] convertToPdf(InputStream inputStream, String originalFileName) { File tempInput null; File tempOutput null; try { // 根据原始文件后缀创建临时输入文件 String suffix getSuffix(originalFileName); tempInput File.createTempFile(input, suffix); FileCopyUtils.copy(inputStream, tempInput); tempOutput File.createTempFile(output, .pdf); LocalConverter.builder() .officeManager(officeManager) .build() .convert(tempInput) .to(tempOutput) .execute(); return FileCopyUtils.copyToByteArray(tempOutput); } catch (Exception e) { throw new RuntimeException(文件转换失败, e); } finally { // 一定记得删除临时文件不然磁盘会被慢慢吃完 if (tempInput ! null) { tempInput.delete(); } if (tempOutput ! null) { tempOutput.delete(); } } }这里有一个非常重要的细节临时输入文件一定要用原始文件的后缀。为什么LibreOffice判断文件类型不是靠文件内容而是靠扩展名。你把一个docx内容保存成input.tmpLibreOffice会把它当成未知类型转换直接失败或者转出乱码。这个坑我第一次踩的时候排查了半天。3. 在线浏览的实现PDF如何优雅地展示在网页上文件转成PDF之后剩下的问题就是怎么在浏览器里展示了。这里有几个方案我按实际使用体验排个序最省事的方式是直接把PDF文件的URL放在浏览器地址栏或者用iframe/object/embed标签嵌入。现代浏览器Chrome、Firefox、Edge、Safari都内置了PDF查看器打开就是原生预览支持翻页、缩放、搜索。代码就一行iframe src/preview/123.pdf stylewidth: 100%; height: 800px;/iframe为什么推荐PDF.js原因有几个第一浏览器兼容性不统一。同样的PDFChrome打开没问题但某些老旧内核的浏览器比如企业里还大量存在的IE内核、360兼容模式是没有内置PDF查看器的打开就是一坨乱码或者直接变下载。第二无法控制交互行为。原生查看器右键就有“另存为”对“不允许下载原文件”这种需求完全没法控制。虽然PDF转换后已经是另一份文件但用户仍然可以把PDF下载走。如果业务要求是“只能看不能拿”还得在此基础上做权限控制比如加水印、禁止打印、分页渲染成图片。第三UI不可定制。项目方经常要求“预览界面和我们系统的风格一致”原生查看器做不到。PDF.js是Mozilla开源的JavaScript库它在网页里自己渲染PDF不依赖浏览器内置能力。核心用法分两步第一步引入pdf.js库script src/static/pdfjs/pdf.min.js/script第二步把PDF字节流交给pdf.js去渲染这里有一个重要的注意点。pdf.js通常有两种加载PDF的方式传PDF文件的URL或者传一个Uint8Array。考虑到文件权限控制更推荐后端返回字节流前端用ArrayBuffer方式加载这样用户拿不到PDF的真实URL也方便做权限拦截async function previewPdf(fileUrl) { const response await fetch(fileUrl); const arrayBuffer await response.arrayBuffer(); const pdf await pdfjsLib.getDocument({ data: arrayBuffer }).promise; const page await pdf.getPage(1); const scale 1.5; const viewport page.getViewport({ scale }); const canvas document.getElementById(pdf-canvas); const context canvas.getContext(2d); canvas.width viewport.width; canvas.height viewport.height; await page.render({ canvasContext: context, viewport, task: new pdfjsLib.RenderTask() }).promise; }上面的代码只渲染了第一页完整版需要写一个循环把所有页都渲染出来。这里让我踩坑的是RenderTask()的用法。如果页面渲染到一半用户翻页或者关闭不取消renderTask的话后台会一直执行渲染内存悄悄涨。所以多页渲染时要维护一个当前渲染任务的引用翻页时先执行renderTask.cancel()再渲染新页面。3.1 PDF.js访问控制的关键点前面提到“不能下载原文件”这个需求做权限控制时有两个层面接口层面预览接口要校验用户登录态和权限不能是公开URL。代码结构上应该是这样RestController RequestMapping(/preview) public class PreviewController { GetMapping(/{fileId}) public ResponseEntitybyte[] preview(PathVariable String fileId, RequestHeader(Authorization) String token) { // 1. 校验token确认用户登录 // 2. 校验用户对该文件的访问权限 // 3. 从文件服务或数据库读取原文件 // 4. 转成PDF // 5. 返回Content-Type: application/pdf } }另外一个安全细节是千万不要把一个永久有效的静态URL暴露给前端。比较稳妥的做法是用一个带过期时间的临时token拼在URL里比如/preview/{fileId}?tokenxxxexpiresxxx后端校验token和过期时间都通过了才返回PDF内容。这样即使URL泄露一段时间后也失效了不会变成永久后门。3.2 转图片展示的备选方案如果你的业务对安全性要求特别高PDF都不能让用户直接拿到完整文件那还有一个方案把PDF逐页转成图片前端只展示图片用户无法获得原始PDF文件。实现思路有两种一种是用PDFBox逐页渲染。Apache PDFBox自带PDF渲染能力PDDocument document PDDocument.load(pdfFile); PDFRenderer renderer new PDFRenderer(document); for (int i 0; i document.getNumberOfPages(); i) { BufferedImage image renderer.renderImageWithDPI(i, 150); ImageIO.write(image, png, new File(outputDir /page_ i .png)); }另一种是转成SVG用SVG做前端展示缩放不失真且可以选中文字但实现复杂度更高。一般图片方案就够用了。这个方案的代价是文件体积膨胀。一页A4纸150DPI的PNG大概一两百KB一个50页的PDF转成图片后体积大约是原始PDF的5到10倍。如果文档量大的话磁盘和带宽压力会上升。4. 常见问题排查与避坑实录整个项目做下来真正耗时间的不是写代码而是解决各种环境问题和边缘case。这里把线上实际遇到的问题整理了几个按出现频率排序。4.1 转换出来的PDF中文全是方块、乱码这个问题几乎人人都能遇到。原因很简单Linux服务器上没有安装中文字体LibreOffice找不到能渲染中文的字体于是用默认字体替换结果替换的字体也不支持中文就变成了方块。排查方法# 查看系统已安装的中文字体 fc-list :langzh如果输出为空说明一个中文字体都没有。解决方法就是安装中文字体最省事的是装fonts-wqy-zenhei或者fonts-wqy-microhei文泉驿正黑和文泉驿微米黑yum install -y fonts-wqy-zenhei fonts-wqy-microhei fc-cache -f提示如果项目涉及合同、公文这类对字形有严格要求的场景建议直接把Windows下的宋体、黑体、仿宋、楷体字体文件simsun.ttc、simhei.ttf、simfang.ttf、simkai.ttf上传到/usr/share/fonts/目录再执行fc-cache -f。项目里的正式文档用宋体排版的情况很多客户看到默认字体变成文泉驿会提意见的。还有一个进阶问题。即使装了字体LibreOffice对docx中“微软雅黑”这类字体的映射也可能不正确因为LibreOffice并没有微软雅黑这个字体它只能用一个近似字体替代。这个问题需要在LibreOffice的字体映射表里手动配置替代规则或者确保文档里用的都是服务器上存在的字体。4.2 转换任务偶尔超时失败系统上线初期用户反馈文档多的时候经常转换失败。排查下来主要原因是并发量超出LibreOffice的处理能力。JODConverter的默认配置里一个OfficeManager管理一个LibreOffice进程一次只能处理一个转换任务。其他任务都在队列里排队。如果单个转换本身就耗时几十秒队列堆积很快后面的任务直接超时。优化的几个方向多端口并行配置多个端口创建多个LibreOffice进程JODConverter会自动分散任务调整超时时间根据实际转换耗时合理设置taskQueueTimeout和taskExecutionTimeout加一层缓存对同一个文件重复转换的场景比如用户反复打开预览可以把转换结果缓存起来。最粗暴的做法是在内存里放一个Mapkey是文件内容的MD5value是转换后的PDF字节流。正式一点用Redis存小文件、磁盘存大文件4.3 加密文档和损坏文档转换报错这个属于典型的输入数据异常。LibreOffice对加密的Office文档转换时会直接拒绝或输出乱码。损坏的docx文件比如zip结构被破坏也会导致转换失败。处理策略是转换前先做文件校验。对于docx/xlsx这类基于OOXML格式的文件本质是个zip包可以尝试用Java的ZipFile打开能正常读取就说明文件结构基本完整。加密文档的判断简单些比如docx的/word/document.xml如果内容是加密的二进制那解压后看不到明文XML结构也算一种判断手段。对这种异常文件业务侧的处理是返回友好的错误提示而不是抛500让用户看到一堆堆栈。在controller层加个全局异常拦截转换失败统一提示“文件格式不正确或已损坏请重新上传”。4.4 临时文件堆积导致磁盘爆满这是个不起眼但是非常致命的问题。转换流程里创建了很多临时文件如果代码里没有正确清理或者进程在转换过程中被kill掉临时文件就会残留在/tmp目录里。线上跑几个月后一个40GB的磁盘可能就被吃光了。解决方式有三道防线第一道代码里在finally块中删除自己创建的临时文件。第二道配置系统定时任务定期清理/tmp下的残留文件# crontab 每天凌晨3点清理 3 天前的转换临时文件 0 3 * * * find /tmp -name input* -mtime 3 -delete; find /tmp -name output* -mtime 3 -delete第三道把临时文件目录从系统盘切到单独的数据盘分区的/tmp/office_convert避免影响系统的其他部分。4.5 大Excel文件转换内存溢出一个20MB的xlsx带大量公式和条件格式LibreOffice转换时内存占用可能超过512MB。这个在容器化部署时特别容易踩。JVM内存和LibreOffice进程内存是分开算的但容器总内存是有限制的。如果部署时只给容器3GBJVM配了2GBLibreOffice再吃1GB就可能OOM。这里有三个层面的优化思路第一层把LibreOffice的可执行文件路径配置成它自己的配置限制其内存使用。可以在JODConverter的配置里指定templateProfileDir或者直接修改LibreOffice的启动参数。第二层上传时就限制文件大小。业务上千方百计想把“能转的文件”范围扩大但性能实测下来超过100MB的xlsx转换时间就很不可控了直接在上传接口做拦截更实际。第三层大文件转换走异步任务。前端先展示“转换中”状态转换完成后通过WebSocket或者轮询通知前端预览。这个体验比同步等待超时好得多也是目前在线预览系统的常规做法。异步架构下同步接口返回的不再是PDF字节流而是一个任务ID。5. 几点复盘建议项目上线后我复盘了一遍有几个体会比较深分享给要做类似功能的同学第一先把文件类型边界定义清楚。不是所有的Office文档都能完美转PDF。比如visio的vsdx文件LibreOffice根本打不开邮件格式的msg转出来效果可能很糟糕。这些边缘格式要提前和业务方对齐明确支持范围不要在项目验收阶段才讨论“为什么这个文件打不开”。第二转换质量要用真实业务文档验证。拿三个从网上下载的模板测试根本不够一定要让业务方提供实际使用的文档类型特别是他们最复杂的几个。比如人事部有几十个自动化表格宏的xlsm转出来可能和Excel里看到的完全不一样。提前暴露问题比上线后处理投诉成本低得多。第三在线预览和在线编辑是两码事。很多业务方口中的“在线浏览”语义其实很模糊有人想要的就是“看个大概”有人想要的是“所见即所得我能复制文字筛选表格”。PDF方案能满足“看”和“复制文字”这类需求但“在线编辑后保存回原格式”是完全不同的技术栈需要OnlyOffice或Collabora这类协作编辑套件。这个边界在需求澄清阶段一定要问清楚不然技术选型会跑偏。最终回头看这个功能的价值在于把用户从“下载文件 - 安装Office - 打开看 - 再关掉”的链条中解放出来直接在网页里完成阅读和轻量操作。技术本身不酷但实打实地解决了用户每天都要重复的痛事。本文还有配套的精品资源点击获取
