JasperReports添加非拉丁字符遇JasperServer Helvetica字体加载异常

问题描述 #

我有如下基础Jasper Report代码：

<?xml version="1.0" encoding="UTF-8"?>
<!-- Created with Jaspersoft Studio version 6.12.2.final using JasperReports Library version 6.12.2-75c5e90a222ab406e416cbf590a5397028a52de3  -->
<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd" name="xxxx" >
    <property name="com.jaspersoft.studio.data.sql.tables" value=""/>
    <property name="com.jaspersoft.studio.data.defaultdataadapter" value="something"/>
    <property name="com.jaspersoft.studio.property.dataset.dialog.DatasetDialog.sash.w1" value="354"/>
    <property name="com.jaspersoft.studio.property.dataset.dialog.DatasetDialog.sash.w2" value="632"/>
    <parameter name="idorder" class="java.lang.String"/>
    <queryString language="SQL">
        <![CDATA[select * from something    where somthing = $P{idorder}]]>
    </queryString>
    <field name="TITRE" class="java.lang.String">
        <property name="com.jaspersoft.studio.field.label" value="TITRE"/>
    </field>        
    <detail>
        <band height="802" splitType="Stretch">
            <property name="com.jaspersoft.studio.unit.height" value="px"/>
            <textField textAdjust="ScaleFont">
                <reportElement uuid="05234b42-f511-431a-8891-1ac49a6758ab"/>
                <textElement textAlignment="Center" verticalAlignment="Middle">
                    <font fontName="Arial" size="22" pdfEncoding="Identity-H"/>
                </textElement>
                <textFieldExpression><![CDATA[$F{TITRE}]]></textFieldExpression>
            </textField>
        </band>
    </detail>
</jasperReport>

为了让标题显示中文字符，我设置了属性pdfEncoding="Identity-H"。该报表在Jaspersoft Studio中运行正常，但上传至JasperServer时出现以下错误：

There was an error on the server. Try again or contact site administrators. 
Could not load the following font: 
pdfFontName: Helvetica
pdfEncoding: Identity-H
isPdfEmbedded : false

我并未在报表中使用Helvetica字体，不清楚错误来源，请问哪里操作有误？

问题原因 #

JasperReports处理PDF输出时，若指定了pdfEncoding="Identity-H"（用于支持Unicode字符，包括中文）但未明确设置pdfFontName，会默认回退到Helvetica字体。而Helvetica本身不支持中文，且JasperServer环境中可能未正确配置该字体的Unicode版本，导致加载失败。

注意：你指定的fontName="Arial"仅用于报表预览、HTML等非PDF输出场景，PDF输出需要单独通过pdfFontName配置对应PDF字体。

解决步骤 #

• 直接修改字体配置：更新<font>标签，添加支持中文的pdfFontName并开启字体嵌入，示例：

  <font fontName="Arial" size="22" pdfFontName="STSong-Light" pdfEncoding="Identity-H" isPdfEmbedded="true"/>
  

  STSong-Light是iText库自带的中文字体，JasperReports默认依赖iText，无需额外配置即可使用。

• 检查版本一致性：确保Jaspersoft Studio与JasperServer使用的JasperReports版本一致（当前为6.12.2），避免版本差异引发的字体解析问题。

• 自定义字体扩展（备选）：若需要使用微软雅黑等自定义字体，可通过JasperReports字体扩展功能实现：

  1. 在Jaspersoft Studio中创建包含目标字体文件的字体扩展
  2. 将扩展包部署到JasperServer的WEB-INF/lib目录
  3. 在报表中引用该扩展字体的名称

关键配置说明 #

• fontName：控制非PDF输出（如预览、HTML）的显示字体
• pdfFontName：专门用于PDF输出的字体，必须支持中文等目标字符集
• isPdfEmbedded="true"：将字体嵌入PDF文件，确保在任意设备上都能正确显示，不依赖系统字体

内容的提问来源于stack exchange，提问作者Thomas Carlton