企业官网建设流程全解析

1. Linux服务器SpringBoot（Docker）项目Word转PDF中文乱码问题解析

最近在部署一个基于SpringBoot的文档处理服务时，遇到了一个典型的中文编码问题：当服务运行在Docker容器中时，Word转PDF功能出现中文乱码。这个问题看似简单，实则涉及操作系统、容器环境、字体配置等多方面因素。经过几天的排查和测试，终于找到了完整的解决方案，这里把整个处理过程和经验总结分享给大家。

这个问题特别容易出现在使用开源库（如Apache POI、iText等）进行文档转换的场景中。当你的服务在本地开发环境运行正常，但部署到Linux服务器的Docker容器后就出现中文乱码时，很可能遇到了和我相同的问题。接下来我会从问题本质、环境分析到具体解决方案，一步步拆解这个"中文乱码"难题。

2. 问题本质与核心原因分析

2.1 乱码问题的技术本质

中文乱码问题本质上是因为系统缺少对应的中文字体，或者字体配置不正确导致的。在Word转PDF的过程中，转换工具需要读取Word文档中的字体信息，并在PDF中正确渲染这些字体。如果系统中没有安装对应的字体，就会使用默认字体替代，导致最终显示的字符与预期不符。

关键点：Word文档中存储的是文字的Unicode编码和字体信息，而PDF需要将文字渲染为图形或嵌入字体。这个转换过程依赖系统字体库。

2.2 典型场景分析

在我们的案例中，问题表现为：

1. 开发环境（Windows/Mac）下转换正常
2. 本地Docker测试中文显示正常
3. 部署到Linux服务器后出现乱码
4. 仅中文乱码，英文和数字显示正常

这种差异主要是因为：

• 开发机器通常安装了完整的中文字体包
• 基础Linux镜像（如alpine、centos等）为了保持轻量，默认不包含中文字体
• Docker容器继承了宿主机的内核，但有自己的文件系统和运行环境

2.3 深层原因排查

通过深入分析，我们发现乱码问题主要涉及三个层面：

1. 系统字体缺失：基础Docker镜像没有安装中文字体
2. 字体配置错误：系统字体缓存未更新或配置不当
3. JVM字体设置：Java应用没有正确识别系统字体

3. 解决方案与实施步骤

3.1 基础环境准备

3.1.1 Dockerfile配置

首先需要在Docker镜像中安装中文字体。以常用的Ubuntu基础镜像为例：

FROM ubuntu:20.04 # 安装中文字体 RUN apt-get update && \ apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* # 其他应用依赖安装...

对于Alpine镜像，可以使用：

FROM alpine:3.14 # 安装中文字体 RUN apk add --no-cache wqy-zenhei

3.1.2 验证字体安装

构建镜像后，进入容器验证字体是否安装成功：

# 查看已安装字体 fc-list :lang=zh # 检查特定字体是否存在 fc-match "WenQuanYi Zen Hei"

3.2 SpringBoot应用配置

3.2.1 确保JVM能识别系统字体

在SpringBoot应用的启动脚本中添加JVM参数：

java -Djava.awt.headless=true \ -Dsun.java2d.fontpath=/usr/share/fonts \ -jar your-application.jar

3.2.2 代码层面的字体指定

如果使用iText进行PDF生成，需要显式指定中文字体：

// 创建字体对象 BaseFont bfChinese = BaseFont.createFont( "STSong-Light", "UniGB-UCS2-H", BaseFont.NOT_EMBEDDED); // 使用字体 Font font = new Font(bfChinese, 12, Font.NORMAL);

3.3 高级配置与优化

3.3.1 字体缓存重建

有时即使安装了字体，系统也可能无法立即识别。需要重建字体缓存：

fc-cache -fv

3.3.2 自定义字体目录

如果不想修改系统字体目录，可以在应用中指定自定义字体路径：

FontFactory.registerDirectory("/path/to/custom/fonts");

3.3.3 字体嵌入PDF

为确保PDF在所有设备上都能正确显示，应该将字体嵌入PDF：

PdfWriter writer = PdfWriter.getInstance(document, outputStream); writer.setPdfVersion(PdfWriter.PDF_VERSION_1_7); writer.setFullCompression(); // 启用字体子集嵌入 writer.setSubsetFont(true);

4. 常见问题与解决方案

4.1 字体安装后仍不生效

问题现象：已经安装了中文字体，但转换后仍然是乱码。

解决方案：

1. 确认字体文件权限：chmod 644 /usr/share/fonts/*
2. 检查JVM字体路径：System.out.println(java.awt.Font.getFontPath())
3. 重启应用服务使字体缓存生效

4.2 特定字符显示异常

问题现象：大部分中文正常，但某些特殊字符显示为方框。

解决方案：

1. 安装更完整的字体包，如fonts-noto-cjk
2. 在代码中指定备用字体：

   FontSelector selector = new FontSelector(); selector.addFont(FontFactory.getFont("SimSun")); selector.addFont(FontFactory.getFont("WenQuanYi Zen Hei"));

4.3 性能优化建议

当处理大量文档转换时，字体处理可能成为性能瓶颈：

1. 字体预加载：在应用启动时预加载常用字体

   FontFactory.register("resources/fonts/simsun.ttf");

2. 使用字体缓存：避免重复创建字体对象

   private static final Font CHINESE_FONT = new Font(bfChinese, 12);

3. 异步处理：将文档转换任务放入线程池处理

5. 完整方案示例

5.1 Dockerfile完整配置

FROM openjdk:11-jre-slim # 设置时区 ENV TZ=Asia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone # 安装中文字体 RUN apt-get update && \ apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei fonts-noto-cjk && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* && \ fc-cache -fv # 复制应用 COPY target/your-app.jar /app.jar # 启动命令 ENTRYPOINT ["java", \ "-Djava.awt.headless=true", \ "-Dsun.java2d.fontpath=/usr/share/fonts", \ "-jar", "/app.jar"]

5.2 SpringBoot代码示例

@Service public class PdfConversionService { private static final String FONT_PATH = "/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc"; private static BaseFont chineseFont; @PostConstruct public void init() throws Exception { // 预加载字体 chineseFont = BaseFont.createFont(FONT_PATH, BaseFont.IDENTITY_H, BaseFont.EMBEDDED); } public void convertWordToPdf(File wordFile, File pdfFile) throws Exception { // 读取Word内容 XWPFDocument doc = new XWPFDocument(new FileInputStream(wordFile)); // 创建PDF文档 Document pdfDoc = new Document(); PdfWriter writer = PdfWriter.getInstance(pdfDoc, new FileOutputStream(pdfFile)); pdfDoc.open(); // 处理Word中的段落 for (XWPFParagraph p : doc.getParagraphs()) { String text = p.getText(); if (StringUtils.isNotEmpty(text)) { Font font = new Font(chineseFont, 12); pdfDoc.add(new Paragraph(text, font)); } } pdfDoc.close(); doc.close(); } }

5.3 测试验证方法

为确保解决方案有效，建议进行以下测试：

1. 基础功能测试：

   @Test public void testChineseRendering() throws Exception { File wordFile = new File("test.docx"); // 包含中文的测试文档 File pdfFile = new File("output.pdf"); conversionService.convertWordToPdf(wordFile, pdfFile); // 验证PDF内容 PDDocument doc = PDDocument.load(pdfFile); PDFTextStripper stripper = new PDFTextStripper(); String text = stripper.getText(doc); assertTrue(text.contains("预期中文内容")); doc.close(); }

2. 字体嵌入验证：

   pdffonts output.pdf

   输出应显示使用的字体及嵌入状态。

6. 经验总结与优化建议

在实际解决这个问题的过程中，我总结了几点重要经验：

1. 环境一致性是关键：开发、测试和生产环境应使用相同的基础镜像和字体配置，避免"在我机器上能运行"的问题。

2. 字体选择有讲究：WenQuanYi（文泉驿）系列字体是开源且支持良好的选择，但某些场景可能需要商业字体（如SimSun）以获得更好的显示效果。

3. 资源释放很重要：字体对象和文档处理流的正确关闭可以避免内存泄漏，特别是在高并发场景下。

4. 监控不可忽视：在服务中增加字体加载检测和健康检查端点，便于及时发现环境问题：

   @GetMapping("/health/fonts") public ResponseEntity<String> checkFonts() { try { Font font = new Font(chineseFont, 12); return ResponseEntity.ok("Fonts available"); } catch (Exception e) { return ResponseEntity.status(503) .body("Font initialization failed: " + e.getMessage()); } }

5. 备选方案考虑：对于复杂的文档转换需求，可以考虑使用专门的转换服务（如LibreOffice in Server Mode），而非纯Java实现。

这个问题的解决过程让我深刻体会到，在容器化部署中，字体这类看似简单的资源也需要特别关注。特别是在处理国际化应用时，基础镜像的选择和配置会直接影响应用的功能表现。