1. 为什么需要Word转PDF动态预览功能在企业级应用开发中文档处理是个绕不开的话题。最近接手一个气象数据分析平台项目客户要求在页面上能直接预览月度、季度的风光资源预测报告Word格式并且支持PDF格式导出。这让我意识到很多业务场景都需要类似的文档处理能力合同管理系统销售部门需要在线预览合同模板法务要确保格式不会错乱报表系统财务部门生成的月度报表需要保持原有排版政务系统红头文件的电子化归档要求格式严格一致Word转PDF最大的优势在于格式固化。我遇到过客户发来的文档在自己电脑上显示正常到别人那里排版全乱的情况。PDF就像给文档拍了张定妆照在任何设备上都能保持原样。而动态预览则让用户不用下载就能快速浏览内容体验提升不是一点半点。2. 技术选型与依赖配置2.1 核心工具对比刚开始调研时我发现Java生态里有好几个方案能处理Word转PDF工具名称优点缺点Apache POI PDFBox纯Java实现无需外部依赖复杂格式转换容易丢失样式OpenPDF开源免费支持中文较好API相对复杂学习成本高docx4j功能强大支持图表转换商业项目需要付费授权poi-tl模板引擎动态生成文档转换PDF需要额外依赖最终选择了fr.opensagres.poi.xwpf.converter这个方案实测下来发现它基于Apache POI开发对.docx格式支持完善转换速度快10页文档平均耗时300ms保留原始文档的页眉页脚、目录结构2.2 Maven依赖配置在pom.xml里需要添加这些关键依赖建议用最新版本!-- Word处理核心库 -- dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependency !-- Word转PDF转换器 -- dependency groupIdfr.opensagres.xdocreport/groupId artifactIdfr.opensagres.poi.xwpf.converter.pdf/artifactId version2.0.4/version /dependency !-- 字体渲染支持 -- dependency groupIdorg.apache.pdfbox/groupId artifactIdpdfbox/artifactId version3.0.0/version /dependency注意如果项目里已经有旧版POI建议先排除掉避免冲突。我就踩过这个坑报错信息是InvalidFormatException折腾半天才发现是版本不兼容。3. 核心代码实现3.1 文档列表接口先实现获取文档目录的功能这里有个实用技巧——用Java NIO的Files.list()比传统File.listFiles()性能更好GetMapping(/list) public ListString listDocuments(RequestParam String type) throws IOException { Path dirPath Paths.get(documents, type); // 按类型分目录 try (StreamPath stream Files.list(dirPath)) { return stream .filter(file - file.toString().endsWith(.docx)) .map(Path::getFileName) .map(Path::toString) .sorted(Comparator.reverseOrder()) // 按文件名倒序 .collect(Collectors.toList()); } }3.2 文档转换核心逻辑转换代码看似简单但有几个关键点需要注意public byte[] convertToPdf(InputStream docxStream) throws IOException { try (XWPFDocument doc new XWPFDocument(docxStream); ByteArrayOutputStream pdfOut new ByteArrayOutputStream()) { // 关键配置设置字体映射 PdfOptions options PdfOptions.create() .fontProvider(new DefaultFontProvider(true, true, true)); PdfConverter.getInstance().convert(doc, pdfOut, options); return pdfOut.toByteArray(); } }这里特别说明下DefaultFontProvider的构造参数第一个true表示嵌入字体到PDF第二个true表示使用系统字体第三个true表示缓存字体数据3.3 前端预览方案推荐两种前端展示PDF的方式方案一PDF.js推荐iframe src/web/viewer.html?file/api/document/preview/月度报告.docx stylewidth:100%; height:80vh; /iframe方案二原生iframe简单但功能弱iframe src/api/document/preview/月度报告.docx typeapplication/pdf styleborder:none; /iframe实测发现PDF.js的渲染效果更好特别是对复杂排版的支持。我在项目中还加了页数导航、缩放控制等扩展功能。4. 字体兼容性难题与解决方案4.1 中文显示异常问题上线第一天就收到用户反馈Linux服务器上生成的PDF全是乱码排查过程很有意思本地Windows环境测试 - 正常测试环境LinuxCentOS - 中文消失对比发现文档用了宋体-18030字体Linux默认没有这个字体4.2 字体安装完整流程在Linux服务器安装字体的正确姿势# 1. 创建字体目录 sudo mkdir -p /usr/share/fonts/custom # 2. 上传字体文件从Windows的C:\Windows\Fonts复制 scp simsun.ttc userserver:/tmp/ # 3. 安装字体 sudo mv /tmp/simsun.ttc /usr/share/fonts/custom/ # 4. 修改权限 sudo chmod 644 /usr/share/fonts/custom/* # 5. 刷新字体缓存 sudo fc-cache -fv # 6. 验证安装 fc-list | grep SimSun4.3 字体映射高级配置更专业的做法是在代码中指定字体替换规则FontProvider fontProvider new DefaultFontProvider() { Override public Font getFont(String familyName, String encoding, byte[] embedded, boolean embeddedSubset) { // 强制指定中文字体映射 if (宋体-18030.equals(familyName)) { return super.getFont(SimSun, encoding, embedded, embeddedSubset); } return super.getFont(familyName, encoding, embedded, embeddedSubset); } };这个技巧帮我解决了90%的字体兼容性问题。剩下的10%需要检查文档是否使用了特殊字符集。5. 性能优化实战经验5.1 缓存策略频繁转换相同文档会消耗CPU我加了二级缓存Cacheable(value documentCache, key #fileName) public byte[] getPdfDocument(String fileName) throws IOException { Path filePath Paths.get(documents, fileName); try (InputStream is Files.newInputStream(filePath)) { return convertToPdf(is); } }配合Spring Cache首次转换后结果存入Redis后续请求直接返回缓存数据。实测QPS从50提升到1200。5.2 异步处理技巧对于大文档超过10MB建议采用异步转换GetMapping(/convert) public CompletableFutureResponseEntityResource asyncConvert( RequestParam String fileName) { return CompletableFuture.supplyAsync(() - { try { byte[] pdf documentService.convertLargeFile(fileName); return ResponseEntity.ok() .header(Content-Type, application/pdf) .body(new ByteArrayResource(pdf)); } catch (Exception e) { throw new RuntimeException(转换失败, e); } }, taskExecutor); }前端可以通过轮询或WebSocket获取处理进度。这个改造让我们的系统能处理50MB以上的气象年报。5.3 内存管理处理大文档时容易OOM推荐配置JVM参数-XX:UseG1GC -XX:MaxRAMPercentage75 -XX:HeapDumpOnOutOfMemoryError另外一定要记得关闭资源流。我曾经因为没关闭XWPFDocument导致服务器内存泄漏教训深刻。6. 企业级应用扩展6.1 文档安全控制给PDF添加水印和权限控制PDDocument pdfDoc PDDocument.load(pdfBytes); PDPage firstPage pdfDoc.getPage(0); // 添加文字水印 PDPageContentStream contentStream new PDPageContentStream( pdfDoc, firstPage, PDPageContentStream.AppendMode.APPEND, true); contentStream.setFont(PDType1Font.HELVETICA_BOLD, 36); contentStream.setNonStrokingColor(200, 200, 200); contentStream.beginText(); contentStream.setTextMatrix(20, 20); contentStream.showText(CONFIDENTIAL); contentStream.endText(); contentStream.close(); // 设置文档权限 AccessPermission ap new AccessPermission(); ap.setCanPrint(false); ap.setCanModify(false); StandardProtectionPolicy spp new StandardProtectionPolicy(ownerpass, , ap); pdfDoc.protect(spp);6.2 与Office 365集成现代企业往往需要对接云办公套件。我们通过Microsoft Graph API实现了直接从OneDrive获取文档GraphServiceClientRequest graphClient ...; InputStream stream graphClient.me() .drive() .items(documentId) .content() .buildRequest() .get(); byte[] pdfBytes converter.convertToPdf(stream);这种方案特别适合已有Office 365租户的企业避免了文档同步问题。6.3 分布式部署方案当系统需要处理高并发文档转换时可以考虑将转换服务拆分成独立微服务使用Kafka队列处理转换请求通过MinIO集中存储生成的PDF文件我们的生产环境部署架构客户端 → Nginx → Spring Boot应用 → Kafka → 转换Worker集群 → MinIO存储这套架构每天能稳定处理10万文档转换请求平均延迟控制在800ms以内。
SpringBoot结合poi实现Word文档动态预览与PDF转换实战
发布时间：2026/7/13 16:34:06
1. 为什么需要Word转PDF动态预览功能在企业级应用开发中文档处理是个绕不开的话题。最近接手一个气象数据分析平台项目客户要求在页面上能直接预览月度、季度的风光资源预测报告Word格式并且支持PDF格式导出。这让我意识到很多业务场景都需要类似的文档处理能力合同管理系统销售部门需要在线预览合同模板法务要确保格式不会错乱报表系统财务部门生成的月度报表需要保持原有排版政务系统红头文件的电子化归档要求格式严格一致Word转PDF最大的优势在于格式固化。我遇到过客户发来的文档在自己电脑上显示正常到别人那里排版全乱的情况。PDF就像给文档拍了张定妆照在任何设备上都能保持原样。而动态预览则让用户不用下载就能快速浏览内容体验提升不是一点半点。2. 技术选型与依赖配置2.1 核心工具对比刚开始调研时我发现Java生态里有好几个方案能处理Word转PDF工具名称优点缺点Apache POI PDFBox纯Java实现无需外部依赖复杂格式转换容易丢失样式OpenPDF开源免费支持中文较好API相对复杂学习成本高docx4j功能强大支持图表转换商业项目需要付费授权poi-tl模板引擎动态生成文档转换PDF需要额外依赖最终选择了fr.opensagres.poi.xwpf.converter这个方案实测下来发现它基于Apache POI开发对.docx格式支持完善转换速度快10页文档平均耗时300ms保留原始文档的页眉页脚、目录结构2.2 Maven依赖配置在pom.xml里需要添加这些关键依赖建议用最新版本!-- Word处理核心库 -- dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependency !-- Word转PDF转换器 -- dependency groupIdfr.opensagres.xdocreport/groupId artifactIdfr.opensagres.poi.xwpf.converter.pdf/artifactId version2.0.4/version /dependency !-- 字体渲染支持 -- dependency groupIdorg.apache.pdfbox/groupId artifactIdpdfbox/artifactId version3.0.0/version /dependency注意如果项目里已经有旧版POI建议先排除掉避免冲突。我就踩过这个坑报错信息是InvalidFormatException折腾半天才发现是版本不兼容。3. 核心代码实现3.1 文档列表接口先实现获取文档目录的功能这里有个实用技巧——用Java NIO的Files.list()比传统File.listFiles()性能更好GetMapping(/list) public ListString listDocuments(RequestParam String type) throws IOException { Path dirPath Paths.get(documents, type); // 按类型分目录 try (StreamPath stream Files.list(dirPath)) { return stream .filter(file - file.toString().endsWith(.docx)) .map(Path::getFileName) .map(Path::toString) .sorted(Comparator.reverseOrder()) // 按文件名倒序 .collect(Collectors.toList()); } }3.2 文档转换核心逻辑转换代码看似简单但有几个关键点需要注意public byte[] convertToPdf(InputStream docxStream) throws IOException { try (XWPFDocument doc new XWPFDocument(docxStream); ByteArrayOutputStream pdfOut new ByteArrayOutputStream()) { // 关键配置设置字体映射 PdfOptions options PdfOptions.create() .fontProvider(new DefaultFontProvider(true, true, true)); PdfConverter.getInstance().convert(doc, pdfOut, options); return pdfOut.toByteArray(); } }这里特别说明下DefaultFontProvider的构造参数第一个true表示嵌入字体到PDF第二个true表示使用系统字体第三个true表示缓存字体数据3.3 前端预览方案推荐两种前端展示PDF的方式方案一PDF.js推荐iframe src/web/viewer.html?file/api/document/preview/月度报告.docx stylewidth:100%; height:80vh; /iframe方案二原生iframe简单但功能弱iframe src/api/document/preview/月度报告.docx typeapplication/pdf styleborder:none; /iframe实测发现PDF.js的渲染效果更好特别是对复杂排版的支持。我在项目中还加了页数导航、缩放控制等扩展功能。4. 字体兼容性难题与解决方案4.1 中文显示异常问题上线第一天就收到用户反馈Linux服务器上生成的PDF全是乱码排查过程很有意思本地Windows环境测试 - 正常测试环境LinuxCentOS - 中文消失对比发现文档用了宋体-18030字体Linux默认没有这个字体4.2 字体安装完整流程在Linux服务器安装字体的正确姿势# 1. 创建字体目录 sudo mkdir -p /usr/share/fonts/custom # 2. 上传字体文件从Windows的C:\Windows\Fonts复制 scp simsun.ttc userserver:/tmp/ # 3. 安装字体 sudo mv /tmp/simsun.ttc /usr/share/fonts/custom/ # 4. 修改权限 sudo chmod 644 /usr/share/fonts/custom/* # 5. 刷新字体缓存 sudo fc-cache -fv # 6. 验证安装 fc-list | grep SimSun4.3 字体映射高级配置更专业的做法是在代码中指定字体替换规则FontProvider fontProvider new DefaultFontProvider() { Override public Font getFont(String familyName, String encoding, byte[] embedded, boolean embeddedSubset) { // 强制指定中文字体映射 if (宋体-18030.equals(familyName)) { return super.getFont(SimSun, encoding, embedded, embeddedSubset); } return super.getFont(familyName, encoding, embedded, embeddedSubset); } };这个技巧帮我解决了90%的字体兼容性问题。剩下的10%需要检查文档是否使用了特殊字符集。5. 性能优化实战经验5.1 缓存策略频繁转换相同文档会消耗CPU我加了二级缓存Cacheable(value documentCache, key #fileName) public byte[] getPdfDocument(String fileName) throws IOException { Path filePath Paths.get(documents, fileName); try (InputStream is Files.newInputStream(filePath)) { return convertToPdf(is); } }配合Spring Cache首次转换后结果存入Redis后续请求直接返回缓存数据。实测QPS从50提升到1200。5.2 异步处理技巧对于大文档超过10MB建议采用异步转换GetMapping(/convert) public CompletableFutureResponseEntityResource asyncConvert( RequestParam String fileName) { return CompletableFuture.supplyAsync(() - { try { byte[] pdf documentService.convertLargeFile(fileName); return ResponseEntity.ok() .header(Content-Type, application/pdf) .body(new ByteArrayResource(pdf)); } catch (Exception e) { throw new RuntimeException(转换失败, e); } }, taskExecutor); }前端可以通过轮询或WebSocket获取处理进度。这个改造让我们的系统能处理50MB以上的气象年报。5.3 内存管理处理大文档时容易OOM推荐配置JVM参数-XX:UseG1GC -XX:MaxRAMPercentage75 -XX:HeapDumpOnOutOfMemoryError另外一定要记得关闭资源流。我曾经因为没关闭XWPFDocument导致服务器内存泄漏教训深刻。6. 企业级应用扩展6.1 文档安全控制给PDF添加水印和权限控制PDDocument pdfDoc PDDocument.load(pdfBytes); PDPage firstPage pdfDoc.getPage(0); // 添加文字水印 PDPageContentStream contentStream new PDPageContentStream( pdfDoc, firstPage, PDPageContentStream.AppendMode.APPEND, true); contentStream.setFont(PDType1Font.HELVETICA_BOLD, 36); contentStream.setNonStrokingColor(200, 200, 200); contentStream.beginText(); contentStream.setTextMatrix(20, 20); contentStream.showText(CONFIDENTIAL); contentStream.endText(); contentStream.close(); // 设置文档权限 AccessPermission ap new AccessPermission(); ap.setCanPrint(false); ap.setCanModify(false); StandardProtectionPolicy spp new StandardProtectionPolicy(ownerpass, , ap); pdfDoc.protect(spp);6.2 与Office 365集成现代企业往往需要对接云办公套件。我们通过Microsoft Graph API实现了直接从OneDrive获取文档GraphServiceClientRequest graphClient ...; InputStream stream graphClient.me() .drive() .items(documentId) .content() .buildRequest() .get(); byte[] pdfBytes converter.convertToPdf(stream);这种方案特别适合已有Office 365租户的企业避免了文档同步问题。6.3 分布式部署方案当系统需要处理高并发文档转换时可以考虑将转换服务拆分成独立微服务使用Kafka队列处理转换请求通过MinIO集中存储生成的PDF文件我们的生产环境部署架构客户端 → Nginx → Spring Boot应用 → Kafka → 转换Worker集群 → MinIO存储这套架构每天能稳定处理10万文档转换请求平均延迟控制在800ms以内。
)
