企业官网建设流程全解析

1. 先看现象：同一个docx在不同平台转出来，PDF为什么能不一样

1.1 一次从“本地正常”到“容器满屏方块”的部署事故

我参与过这样一个文档转换服务：用户上传 docx，服务端用 Aspose.Words 把 Word 转成 PDF，再自动加一层“内部资料”水印，整个过程对外表现得像一次普通在线预览。刚开始跑在开发机上，输出 PDF 几乎和原文档排版一致，大家没觉得会有任何问题。后来同事换了 Mac，用同一份测试文件转换，中文字体肉眼可见地变粗、变瘦，英文单词间距也时而宽时而窄。再后来服务打包成 Docker 镜像部署到测试环境，打开 PDF 直接是满屏的方框和乱码，汉字基本没法看。

这不是 Aspose.Words 自身转坏了，而是字体体系出了问题。Aspose.Words 本身不是字体厂家，它把字体的发现、加载和替换完全交给运行环境。Windows 上能找到宋体、黑体、Arial；macOS 上有苹果自己的中文字体和一堆西文字体；但一个精简的 Linux 容器镜像里，可能连 fontconfig 都没有，更别提中文字体文件。结果就是同一个 docx，换一个环境输出，PDF 就跟着变成另一个样子。

1.2 乱码到底是什么：缺失字体、替换字体、编码错乱

很多人一看到“乱码”就往字符编码上想，但在这里需要分清楚。PDF 里出现方块、空格、错位字形，往往是“缺字形”而不是“字符编码错了”。docx 内部的 document.xml 保存的是字符编码和字体名称，比如中文字体叫“宋体”，英文字体叫“Times New Roman”。转换时，Aspose.Words 会拿着这些字体名去系统里找同名或近似字体；找不到时，它就会用自己的一套替换逻辑选一个字体，再不行就交给系统字体回退。

所以你能看到三类现象：

这类问题在 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. 跑通跨平台的最小代码：依赖、许可、加水印和转 PDF

2.1 Maven 依赖和许可证初始化

我用的是 Java 技术栈，项目里通过 Maven 管理依赖。Aspose.Words 的 Java 包可以直接从 Maven 仓库拉取，但注意它体积不小，而且需要你自己在启动时初始化授权文件。没有授权文件时，它会在生成的 PDF 上额外叠加一个“Evaluation Only”水印，这会跟你自己加的水印混在一起，排查时会很误导人。

<dependency> <groupId>com.aspose</groupId> <artifactId>aspose-words</artifactId> <version>24.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转成 PDF：

import 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 :lang=zh | head -20 fc-match "宋体"

如果fc-list :lang=zh没有任何输出，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:MaxRAMPercentage=75" \ 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 类与自定义 Shape

4.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 配额，转换稍大文档就 OOM，K8s 反复重启。

对于 Java 应用，推荐让 JVM 自动适配容器配额，而不是写死-Xmx：

java -XX:MaxRAMPercentage=75 -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 最后的检查清单

我把这次踩坑总结成一张速查表，每次升级基础镜像或更换字体时，我会按这个顺序过一遍：

这套流程走完之后，Mac/Linux/Docker 环境下的乱码问题基本都能被定位到具体环节。后来我们把同样的流程用到了另一个批量盖章项目里，换汤不换药：环境先补充字体，再让 Aspose 知道字体路径，最后用 PDF 字体检测工具确认肉眼看到的结果。字体问题一旦形成方法论，就不再可怕了。