1. 先看现象同一个docx在不同平台转出来PDF为什么能不一样1.1 一次从“本地正常”到“容器满屏方块”的部署事故我参与过这样一个文档转换服务用户上传 docx服务端用 Aspose.Words 把 Word 转成 PDF再自动加一层“内部资料”水印整个过程对外表现得像一次普通在线预览。刚开始跑在开发机上输出 PDF 几乎和原文档排版一致大家没觉得会有任何问题。后来同事换了 Mac用同一份测试文件转换中文字体肉眼可见地变粗、变瘦英文单词间距也时而宽时而窄。再后来服务打包成 Docker 镜像部署到测试环境打开 PDF 直接是满屏的方框和乱码汉字基本没法看。这不是 Aspose.Words 自身转坏了而是字体体系出了问题。Aspose.Words 本身不是字体厂家它把字体的发现、加载和替换完全交给运行环境。Windows 上能找到宋体、黑体、ArialmacOS 上有苹果自己的中文字体和一堆西文字体但一个精简的 Linux 容器镜像里可能连 fontconfig 都没有更别提中文字体文件。结果就是同一个 docx换一个环境输出PDF 就跟着变成另一个样子。1.2 乱码到底是什么缺失字体、替换字体、编码错乱很多人一看到“乱码”就往字符编码上想但在这里需要分清楚。PDF 里出现方块、空格、错位字形往往是“缺字形”而不是“字符编码错了”。docx 内部的 document.xml 保存的是字符编码和字体名称比如中文字体叫“宋体”英文字体叫“Times New Roman”。转换时Aspose.Words 会拿着这些字体名去系统里找同名或近似字体找不到时它就会用自己的一套替换逻辑选一个字体再不行就交给系统字体回退。所以你能看到三类现象现象内在原因典型场景汉字变成“豆腐块”系统中没有任何提供中文字形的字体精简 Docker 基础镜像中文字形变化但能识别字体被替换成另一个中文字体macOS / Linux 没有原字体英文间距、数字基线不对西文被替换成 metrics 不一致的替代字体缺少 Arial、Times New Roman 等常用西文这类问题在 Windows 下很少暴露因为 Office 环境本身就预装了大量字体。但在 Mac/Linux/Docker 环境你必须在“环境”层面主动补齐字体并且让 Aspose.Words 知道去哪里找。这也是后续所有排查工作的核心。1.3 为什么 Mac 和 Linux 表现还不一样Mac 有系统字体库所以不会出现满屏方块但 Mac 上的“宋体”其实对应的是“宋体-简”这类系统命名和 Windows 上的“宋体”不完全等价。Aspose.Words 碰到字体名不匹配时会走替换。Linux 桌面版通常会装一些开源字体比如 DejaVu 系列、Noto 系列所以部分字体能显示但如果你没有装中文 CJK 字体中文字符照样缺失。Docker 就更特殊。很多镜像为了控制体积只保留最基本运行时依赖。我自己踩过最狠的一次是镜像里连fc-list都没有/usr/share/fonts目录完全不存在Aspose.Words 找不到任何系统字体源最后只能把所有文本画成一个兜底字体。这时候再谈字体兼容就是空话必须先让环境拥有“字体生态”。2. 跑通跨平台的最小代码依赖、许可、加水印和转 PDF2.1 Maven 依赖和许可证初始化我用的是 Java 技术栈项目里通过 Maven 管理依赖。Aspose.Words 的 Java 包可以直接从 Maven 仓库拉取但注意它体积不小而且需要你自己在启动时初始化授权文件。没有授权文件时它会在生成的 PDF 上额外叠加一个“Evaluation Only”水印这会跟你自己加的水印混在一起排查时会很误导人。dependency groupIdcom.aspose/groupId artifactIdaspose-words/artifactId version24.x/version /dependency具体版本号根据你本地的 JDK 版本和授权许可文件来选不要盲目追求最新版。授权初始化通常在 Spring 容器的启动阶段或是一个单例方法里做只需要执行一次import com.aspose.words.License; import java.io.FileInputStream; import java.io.InputStream; public class AsposeLicenseBootstrap { public static void init() throws Exception { try (InputStream lic new FileInputStream(/config/Aspose.Words.lic)) { License license new License(); license.setLicense(lic); } } }2.2 最小可运行的转换docx 加水印并导出 PDF这是整个服务的核心代码。注意这里的水印是加在 Word 文档层面的然后再一次save转成 PDFimport com.aspose.words.Document; import com.aspose.words.SaveFormat; import com.aspose.words.TextWatermarkOptions; import com.aspose.words.WatermarkLayout; public class DocxToPdfWithWatermark { public void convert(String inputPath, String outputPath) throws Exception { Document doc new Document(inputPath); TextWatermarkOptions watermarkOptions new TextWatermarkOptions(); watermarkOptions.setFontFamily(Noto Sans CJK SC); watermarkOptions.setFontSize(48); watermarkOptions.setColor(new java.awt.Color(180, 180, 180)); watermarkOptions.setLayout(WatermarkLayout.DIAGONAL); watermarkOptions.setSemitransparent(true); doc.getWatermark().setText(内部资料, watermarkOptions); doc.save(outputPath, SaveFormat.PDF); } }这段代码在本地跑通很容易但丢进容器前你要先回答一个问题容器里究竟有没有Noto Sans CJK SC这个字体如果没有Aspose.Words 大概率会替换成默认字体水印和正文一起乱。2.3 为什么我坚持先加 Word 水印再转 PDF你可能想到另一个方案先把 Word 转成纯 PDF再用第三方 PDF 库往上叠一层水印。这个方案不是不行但它有两个明显麻烦。第一PDF 内容流不像 Word 那样有清晰段落结构你要在指定页面坐标插入旋转文本、半透明图层需要额外处理很多底层细节。第二如果原始文档有多页且内容动态增长PDF 水印可能不会自动出现在新页面正确位置。Word 水印则是原生能力它挂在文档的节、页眉或页脚结构中。转 PDF 时水印会随页面输出页数多少都不影响。而且如果用户后续需要把 PDF 里的文字复制出来文字仍然是文字而不是图片水印可访问性也好很多。3. 乱码的完整排查链路从字体发现到容器字体包3.1 先搞清楚 Aspose.Words 实际看到哪些字体排错不能靠猜。Aspose.Words 的FontSettings对象可以列出当前的字体源。你可以临时写一个小工具把系统里的可用字体全部打印出来看看是不是有你已经装好的中文字体import com.aspose.words.Document; import com.aspose.words.FontSettings; import com.aspose.words.FontSourceBase; import com.aspose.words.SystemFontSource; import com.aspose.words.PhysicalFont; public class FontInspector { public static void printFonts() throws Exception { Document doc new Document(); FontSettings settings doc.getFontSettings(); FontSourceBase[] sources settings.getFontsSources(); for (FontSourceBase source : sources) { System.out.println(source type: source.getType()); PhysicalFont[] fonts source.getAvailableFonts(); for (PhysicalFont font : fonts) { String name font.getFullFontName(); if (name.contains(Noto) || name.contains(CJK) || name.contains(DejaVu)) { System.out.println(name); } } } } }如果在 Docker 里运行这段代码结果只有 DejaVu Sans那说明中文字体确实没有安装。你要做的不是继续调 Java 代码而是先回到镜像层把字体装上。3.2 用 fontconfig 对容器做“字体体检”在 Linux 容器里最直接的手段是安装fontconfig工具包然后用fc-list查看系统已经注册的字体。fc-match则能告诉你当程序要求某个字体时系统会用哪个字体来兜底。# 在容器内执行 fc-list :langzh | head -20 fc-match 宋体如果fc-list :langzh没有任何输出fc-match 宋体返回的也不是一个中文字体那就说明系统层面根本没有中文字体可用。之后再排查 Aspose 就是浪费时间先把环境问题解决掉。3.3 Docker 镜像里装字体的两种稳妥方式第一种是直接用操作系统包管理器安装开源字体。下面这段 Dockerfile 是从生产环境里抽出来的核心片段# 这里用你自己团队维护的基础镜像替换成带 glibc 的 JRE 镜像即可 FROM base-jre-17 RUN apt-get update apt-get install -y \ fontconfig \ fonts-noto-cjk \ ttf-dejavu \ rm -rf /var/lib/apt/lists/* COPY ./fonts /usr/share/fonts/custom RUN fc-cache -f /usr/share/fonts/custom这里提一个关键点尽量别用 Alpine 作为 Aspose.Words 的运行时基础镜像。Alpine 用的是 musl libc而 Aspose.Words 的 Java 包在运行时依赖一些 native 字体处理逻辑兼容性上不如 Debian/Ubuntu 这类 glibc 系统。如果你已经用了 Alpine建议换掉能省掉很多莫名其妙的问题。第二种方式是把字体作为外部挂载点在 docker compose 或 K8s 里把宿主机字体目录挂进容器docker run --rm \ -v /data/fonts:/usr/share/fonts/custom:ro \ -e JAVA_OPTS-XX:MaxRAMPercentage75 \ your-doc-convert-image这种方式适合字体文件频繁更新、不方便重新打镜像的业务场景。但要警惕目录权限问题只读挂载是基本要求。3.4 通过 FontSettings 告诉 Aspose 去哪里找字体环境里有了字体还不够。Aspose 默认会自动扫描系统字体源但如果你想额外指定一个字体目录千万不要使用被废弃的setFontsFolder简单方法因为某些版本里它会直接替换掉原有字体源导致系统字体也扫不到。稳妥做法是显式构造字体源数组把系统字体源和自定义目录都放进去import com.aspose.words.Document; import com.aspose.words.FontSettings; import com.aspose.words.FontSourceBase; import com.aspose.words.SystemFontSource; import com.aspose.words.FolderFontSource; public class FontConfig { public static void applyFontSources(Document doc) { FontSettings settings doc.getFontSettings(); FontSourceBase[] sources new FontSourceBase[]{ new SystemFontSource(), new FolderFontSource(/usr/share/fonts/custom, true), new FolderFontSource(/opt/third-party-fonts, true) }; settings.setFontsSources(sources); } }第二个参数true表示递归扫描子目录。目录越深、字体文件越多首次扫描越慢所以生产环境建议把字体文件集中到一个相对扁平的目录里。3.5 输出 PDF 时的字体内嵌策略字体问题还可能需要从 PDF 导出这一步兜底。如果你遇到的是“开发机转出来正常用户设备上打开乱码”那很可能不是转换环境缺字体而是 PDF 没有嵌入字体。默认情况下如果转换环境有对应字体Aspose 会按需嵌入但为了保险我通常会显式开启完整字体嵌入import com.aspose.words.PdfSaveOptions; PdfSaveOptions pdfOptions new PdfSaveOptions(); pdfOptions.setEmbedFullFonts(true); doc.save(outputPath, pdfOptions);这样做会让生成 PDF 体积更大但换来了跨设备稳定性。如果你的在线预览系统对文件体积很敏感可以在测试环境对比一下看看是否所有字体都能正确嵌入再决定要不要全量开启。3.6 最终验证pdffonts 是最好的“照妖镜”转出来的 PDF 是否还有字体问题不要靠肉眼看完就下结论。我习惯在容器里安装poppler-utils然后用pdffonts查看字体列表pdffonts output.pdf看两个重点一是字体名称是否是预期字体比如NotoSansCJKsc-Regular二是状态列是否显示embedded subset。如果显示not embedded说明字体没有进入 PDF后续在其他设备上很可能出问题。这个命令配合fc-list基本能把整个乱码链路锁定在某个环节上。4. 水印实现的两条路线内置 Watermark 类与自定义 Shape4.1 内置 Watermark 类适合绝大多数“机密文件”场景Aspose.Words 的Watermark类封装了 Word 原生水印逻辑最大的优点是简单。你只需要设置一次水印文本、字体、颜色、布局Document 里所有页都会自动出现。代码已经在前面出现过我再补充一个实际经验水印字体不要随便填Arial或宋体而要看容器里实际存在的字体。如果水印字体缺失水印也会变成方块和你正文乱码一起出现。WatermarkLayout.DIAGONAL是斜对角水印WatermarkLayout.HORIZONTAL是横向平铺水印。内部资料、草稿、绝密这类水印用斜向比较合适既能覆盖正文又不影响阅读。4.2 自定义 Shape应对图形水印、多行水印和特殊坐标Watermark 类能满足 80% 的文本水印需求但有一些场景它搞不定比如水印是公司 Logo 图片比如水印需要重复多行并精确控制间距比如水印要放在固定坐标而不是 Word 原生水印的排版区域。这时可以退回到 Shape 方案插入一个文本框形状设置旋转、缩放、颜色、层级用完后通过 Aspose 的布局引擎输出到 PDF。下面是一个常见的“CONFIDENTIAL”斜向水印实现import com.aspose.words.*; public class CustomShapeWatermark { public static void addWatermark(Document doc) throws Exception { Shape watermark new Shape(doc, ShapeType.TEXT_BOX); watermark.setWidth(300); watermark.setHeight(120); watermark.setRotation(-30); watermark.setBehindText(true); watermark.setRelativeHorizontalPosition(RelativeHorizontalPosition.PAGE); watermark.setRelativeVerticalPosition(RelativeVerticalPosition.PAGE); watermark.setHorizontalAlignment(HorizontalAlignment.CENTER); watermark.setVerticalAlignment(VerticalAlignment.CENTER); TextPath textPath watermark.getTextPath(); textPath.setText(CONFIDENTIAL); textPath.setFontFamily(Noto Sans CJK SC); textPath.setSize(40); textPath.setBold(true); watermark.getFill().setColor(new java.awt.Color(200, 200, 200)); watermark.getStroke().setColor(new java.awt.Color(200, 200, 200)); doc.getFirstSection().getBody().appendChild(watermark); } }用 Shape 时要注意旋转字段的单位是角度正数按顺时针负数按逆时针颜色尽量用浅灰而不是纯黑否则会严重影响正文可读性。4.3 多 Section 文档的“水印只出现在第一页”问题曾经有个奇怪现象用户上传的 docx 有封面、目录、正文多个节加水印后只有第一页有水印。排查后发现是文档里不同 section 使用了完全独立的“无页眉页脚”设置Word 原生水印挂在页眉层上之后section的页面属性切断了继承关系。如果没有升级版本的便利条件最直接的处理是遍历所有 section把水印形状统一插入到每个 section 的页眉里而不是只加在 first section 的 body 上。只要你想让水印覆盖整份 PDF都要把“多节”这个因素算进去。Watermark类在一些版本上也是针对于当前节或封装了统一逻辑但遇到复杂文档时靠 Shape 手动遍历是更可控的import com.aspose.words.*; public class MultiSectionWatermark { public static void applyToAllSections(Document doc) throws Exception { for (Section section : doc.getSections()) { HeaderFooter header section.getHeadersFooters().get(HeaderFooterType.HEADER_PRIMARY); Shape watermark buildShape(doc); header.appendChild(watermark); } } private static Shape buildShape(Document doc) throws Exception { Shape watermark new Shape(doc, ShapeType.TEXT_BOX); watermark.getTextPath().setText(内部资料); watermark.setWidth(280); watermark.setHeight(80); watermark.setRotation(-35); watermark.setBehindText(true); watermark.setHorizontalAlignment(HorizontalAlignment.CENTER); watermark.setVerticalAlignment(VerticalAlignment.CENTER); watermark.getFill().setColor(new java.awt.Color(220, 220, 220)); watermark.getStroke().setColor(new java.awt.Color(220, 220, 220)); return watermark; } }这种方式虽然代码多但它能保证每个 section 页面的水印位置一致。4.4 水印字体和正文字体一起被 Fallback 坑水印本身也是文本它同样会经历字体解析流程。如果你的系统字体源里没有水印指定的字体纵然水印代码写得再好最终 PDF 里也会用另一个字体渲染甚至出现缺失。所以在 Dockerfile 和 FontSettings 配置完成后我建议你单独转一份只带水印的测试文档先用pdffonts确认水印字体确实内嵌再考虑大规模接入业务。5. 容器里的生产化收尾并发、内存、字体缓存和验证5.1 限制内存时先想清 JVM 与 Aspose.Words 的关系容器部署时最容易踩的坑是只给 JVM 很小的堆内存。Aspose.Words 加载 docx 需要把文档解析成内存对象遇到几十 MB 的 PPT/Word 文件内存会放大到几百 MB。我见过一个服务在 Kubernetes 里只给了 512MB 配额转换稍大文档就 OOMK8s 反复重启。对于 Java 应用推荐让 JVM 自动适配容器配额而不是写死-Xmxjava -XX:MaxRAMPercentage75 -jar app.jar这样容器限制是多少JVM 就按 75% 的比例来设置堆上限给元空间、线程栈、native 内存留下余量。MaxRAMPercentage在 JDK 8u191 之后的版本更可靠如果你还在用特别老的 JDK建议升级到 17 或更高版本。5.2 Document 对象不能共享但可以共享模板字节流另一个典型错误是用 Spring 单例对象缓存一个Document然后多个请求并发调用它去转 PDF。这样会随机出现文档内容串页、水印错乱严重时直接抛异常。Document对象不是线程安全的必须保证每个请求自己加载一份新文档。但你可以把 docx 原始字节流缓存到内存或 Redis 中每次转换时从同一个模板字节流新建Document这样既能减少磁盘 I/O又不会发生并发共享冲突byte[] templateBytes loadTemplateFromCache(); Document doc new Document(new ByteArrayInputStream(templateBytes)); performConvert(doc); doc.close();5.3 字体扫描预热和动态更新的取舍容器启动后第一次转换通常比后续转换慢因为 Aspose 需要扫描大量字体文件。针对在线预览这种低延迟业务我建议在应用启动完成时主动加载一份空白文档并调用FontSettings.getFontsSources()强制完成一次字体扫瞄。Scanner 的缓存是 JVM 级的预热一次后续转换就会快很多。但字体缓存也有副作用如果你在容器运行过程中往字体目录里加了新字体Aspose 可能不会立刻感知。所以生产环境要么固定字体目录不随便动要么通过版本化镜像的形式一次性更新字体。5.4 一些容易被忽视的日志和权限问题最后提醒一个容易踩但很隐蔽的细节让容器以非 root 用户运行字体目录只给“读”权限。某些团队为了图省事直接以 root 运行一旦字体目录被误配成可写转出来的 PDF 偶尔会有奇怪的字体路径权限报错。正确的做法是在 Dockerfile 末尾创建专用用户RUN useradd --create-home --uid 1000 app USER app如果在 Windows 和 Mac 下转换正常、在 Linux 下偶尔报 “Cannot read font” 异常优先检查运行身份是否对/usr/share/fonts有读权限。5.5 最后的检查清单我把这次踩坑总结成一张速查表每次升级基础镜像或更换字体时我会按这个顺序过一遍检查项命令或操作预期结果容器是否有中文字体fc-list :langzh输出 Noto CJK 等字体指定字体能否命中fc-match 宋体返回可渲染字体名称Aspose 是否扫描到字体打印FontSettings.getFontsSources()能看到对应字体源PDF 字体是否内嵌pdffonts output.pdf状态列显示 embedded subset并发是否安全每个请求新建 Document无共享异常JVM 是否会被 OOMKilled日志中无 OutOfMemoryError容器内存配额足够这套流程走完之后Mac/Linux/Docker 环境下的乱码问题基本都能被定位到具体环节。后来我们把同样的流程用到了另一个批量盖章项目里换汤不换药环境先补充字体再让 Aspose 知道字体路径最后用 PDF 字体检测工具确认肉眼看到的结果。字体问题一旦形成方法论就不再可怕了。