Java html转PDF字体问题处理

最新推荐文章于 2025-06-16 09:09:02 发布

最新推荐文章于 2025-06-16 09:09:02 发布 · 1.4k 阅读

文章标签：

#java #html #pdf

java 同时被 3 个专栏收录

114 篇文章

订阅专栏

异常报错

71 篇文章

订阅专栏

Linux

34 篇文章

订阅专栏

文章目录

Java html转PDF

项目需求，需要实时生成一个催收函，在APP上展示和提供下载。此催收函包含客户当前最新的欠款情况，包括期数、预期利息等，都是每天实时计算的结果。由于欠款期数不同，会以一个表格的形式展示
实时生成PDF，最简单的思路，就是根据模板文件，动态赋值和修改模板内容，再转换为PDF文件
在Java中将HTML转换为PDF通常需要使用第三方库，可以选择使用开源的库，比如Flying Saucer
还有其他一些Java库，如Apache PDFBox和iText，也可以用于HTML到PDF的转换
由于项目里已经引入了iText，就决定使用这个

Linux里html转换时中文丢失

使用iText将html转换为PDF时很方便，几行代码就能搞到，很快在本地测试通过，部署到了测试环境
部署到测试环境后，问题来了，转换的中文没了
中文字符丢失的问题，通常是因为缺少合适的字体支持。本地测试时，由于本机是Windows机器，系统所带的字体集也比较全，都是可以直接调用到。到了Linux系统时，并没有默认就对中文提供支持
iText 默认不包含所有字体，因此需要手动指定可以支持中文字符的字体。找到我们需要的字体文件，例如，按照绝对路径引入加载进来即可
引入字体文件，修改代码，重新部署，果然没问题了，本地Windows环境测试没问题

Linux系统字体文件不生效

Windows环境测试没问题，Linux环境有问题
一开始是把字体文件放到项目工程（resources下面，打包到classes）里面的，想着打包部署比较方便
可明明有了字体文件，咋识别不到呢？想了想，在Windows环境也没问题，是因为可能压根没使用我上传的文件，而是使用了系统自带的文件
在Linux里，我们使用的是docker虚拟机，jar包里的字体文件，根本识别不到，加载不进去
在宿主机上存了下字体文件，做了映射，这次可以了，能读取到了，能正常转换和展示中文了
很简单：在Linux环境使用时，最好放到固定位置，使用绝对路径去加载

生产环境报LucidaBright-DemiDemibold受限

测试环境没问题后，需求正常测试和上线。结果上线当天，又出了问题，遇到字体 Lucida Bright Demi Demibold 报告受限的错误。测试环境完全没遇到这个报错，搜索了下，发现这是个商用字体
LucidaBright-DemiDemibold 字体是商业字体，需要获得许可才能用于商业目的。它不属于免费商用字体，如果需要在商业项目中使用 LucidaBright-DemiDemibold 字体，需要购买合法的许可证以确保使用符合版权要求
非常奇怪，测试环境和生产环境，都是Linux系统里使用docker部署，都是同样的代码和镜像。但是没办法，就是这么发生了，难道这个字体还能自动监测是不是生产环境，自动判断可能是商用？
而且我也没用这个字体啊，我用的是宋体和楷体，于是开始搜索解决，发现了端倪
在使用 Java 将 HTML 转换为 PDF 时，如果遇到字体 Lucida Bright Demi Demibold 报告受限的错误，即使你没有明确使用它，可能是因为以下几个原因：

可能的原因

HTML 内容中的字体指定
如果你的 HTML 或 CSS 中指定了 Lucida Bright 或任何其他与该字体相关的字体族，当生成 PDF 时，转换器可能会尝试查找并使用该字体。如果系统中未安装该字体，或者无权访问，可能会导致错误。
默认字体设置
一些 PDF 转换库（如 iText、Apache PDFBox 等）在处理文本时可能会有默认字体设置。如果这些设置使用了 Lucida 字体，而该字体又不可用，则会出现此问题。
外部资源
如果 HTML 中引用了外部样式表或字体（如 @font-face），而该字体给出了 Lucida Bright 的链接，也可能会引发这个问题。

解决方案

检查 HTML 和 CSS
查看你的 HTML 和 CSS 文件，确保没有引用 Lucida Bright 或相关字体。如果有，把它们替换为可用的字体。
指定备用字体
在你的 CSS 文件中为所有字体声明添加备用字体。这样，即使所需字体不可用，PDF 生成器也能使用备用字体。

body { 
	font-family: 'Noto Sans CJK','Fangzheng Fang Song', 'STFANGSO', '仿宋', 'SimSun', sans-serif;/* 备选字体 */
}

嵌入字体
如果你确实需要使用该字体，可以考虑将其嵌入到 PDF 中。大多数 PDF 库允许你将字体文件包含在生成的 PDF 中，确保它可以被正确渲染。
检查日志
查看转换过程中的详细错误日志，有时候可以找到更具体的提示，帮助你确定是哪一部分触发了字体错误。考虑到有时候由于代码框架问题，异常没有抛出和打印，可以考虑自己加一行log.error的打印帮助排查问题。

后续

要确保在 HTML/CSS 中没有引用无法使用的字体，并适当地使用备用字体。于是我修改了模板html文件，删除内容里的字体定义，全部写在全局里，加了要用的字体和默认字体
在转换代码里，设置不使用默认字体，引入需要的字体，通过显式的排除和引入确保使用了想要的字体
考虑版权及商用收费的问题，绝对不要用微软字体或者其他可能收费字体。其实一些免费的宋体（思源宋体、方正宋体等），看起来也都差不多，转换使用无感的。

总结

iText将html转换为PDF时很方便很好用
需要严格设置字体，不要加没有引入字体文件内的字体，包括css里和html里
按需引入字体文件，排除默认的字体文件，字体文件要放到服务器上，绝对路径引入
完整版代码如下：

/**
     * 将HTML转成PDF文件
     * @param html
     * @param path
     * @param fileName
     * @return
     */
    public static File htmlToPdf(String html, String path, String fileName, String fontPath) {
        String pdfPath = path + File.separator + fileName;
        File file = new File(path);
        if (!file.exists()) {
            file.mkdirs();
        }
        File pdfFile = new File(pdfPath);
        log.info("pdfFile.toPath() : {}", pdfFile.toPath());
        try(OutputStream outputStream = new FileOutputStream(pdfFile)) {
            // 转换 HTML to PDF
            PdfWriter writer = new PdfWriter(outputStream);
            PdfDocument pdfDocument = new PdfDocument(writer);
            // 设置PDF大小
            pdfDocument.setDefaultPageSize(PageSize.A4);
            // 设置中文
            String fontPath1 = fontPath + "/NotoSansCJK.ttc";
            log.info("font1 path : {}", fontPath1);
            // 设置中文
            String fontPath2 = fontPath + "/FangZhengFangSongJianTi-1.ttf";
            log.info("font2 path : {}", fontPath2);
            // 设置中文
            String fontPath3 = fontPath + "/STFANGSO.TTF";
            log.info("font3 path : {}", fontPath3);

            ConverterProperties props = new ConverterProperties();
            DefaultFontProvider defaultFontProvider = new DefaultFontProvider(false, false, false);
            defaultFontProvider.addFont(fontPath1);
            defaultFontProvider.addFont(fontPath2);
            defaultFontProvider.addFont(fontPath3);
            props.setFontProvider(defaultFontProvider);

            // html转换PDF
            HtmlConverter.convertToPdf(html, pdfDocument, props);

            // 关闭
            pdfDocument.close();
        } catch (Exception e){
            e.printStackTrace();
            log.error("\n\n=================写入文件失败：{}==================", e.getMessage());
        }

        return pdfFile;
    }