优先使用 jasperreports-bom 管理版本，显式排除 xml-apis、commons-collections4 等冲突依赖；确保 jasperreports-fonts 与主包版本一致；.jrxml 须存为 utf-8 编码，编译前调用 jrfontutil.registerfonts()，模板中 textelement 显式设置 pdffontname 和 pdfencoding；资源路径用 getclass().getresource() 获取，避免硬编码；pdf 导出异常多因分页配置不当或字体嵌入失败。
用 Maven 引入 JasperReports 依赖时，版本冲突很常见
直接加 jasperreports 依赖容易和 Spring Boot 内置的 xml-apis、batik 或旧版 commons-collections 冲突，编译不报错但运行时报 NoClassDefFoundError 或模板加载失败。
- 优先用官方推荐的 BOM 管理依赖：在
pom.xml的<dependencymanagement></dependencymanagement>中引入jasperreports-bom，再声明具体模块（如jasperreports、jasperreports-fonts） - 显式排除 Spring Boot 自带的冲突传递依赖，比如：
xml-apis、commons-collections4（JasperReports 6.x 仍依赖commons-collections3.x） - 字体渲染问题多源于
jasperreports-fonts版本不匹配，务必确认它和主包版本一致（例如都用6.20.0）
模板（.jrxml）编译成 .jasper 时，中文乱码或字体不生效
不是模板写错了，而是编译环节缺失字体注册和编码配置。JasperReports 默认不加载系统字体，也不自动识别 UTF-8 模板文件编码。
- 确保
.jrxml文件本身保存为 UTF-8 编码（IDE 中检查右下角编码标识） - 在编译前调用
JRXmlCompiler.compileReport()前，先执行JRFontUtil.registerFonts()（需提前加载jasperreports-fontsJAR） - 模板中所有
<textelement></textelement>必须显式设置pdfFontName和pdfEncoding，例如：pdfFontName="Helvetica"+pdfEncoding="Cp1252"不支持中文；应改用pdfFontName="SimSun"（需字体文件存在）+pdfEncoding="Identity-H"
Spring Boot 项目里动态填充报表，class path 路径容易搞错
JasperCompileManager.compileReport() 和 JasperFillManager.fillReport() 对资源路径非常敏感，用错路径会抛 JRException: Could not load object from location。
- 模板文件放在
src/main/resources/reports/下，代码中用getClass().getResource("/reports/template.jrxml")获取 URL，不要拼字符串路径 - 如果用
compileReport()编译，必须传入InputStream（推荐getResourceAsStream()），不能传相对路径字符串 - 生成的
.jasper文件别硬写到/tmp或项目根目录——Spring Boot 打成 jar 后这些路径不可写，建议用new File(System.getProperty("java.io.tmpdir"))
导出 PDF 时空白页、表格截断或分页异常
这不是 JasperReports bug，而是模板设计阶段没适配分页逻辑导致的。PDF 导出器对 isSplitAllowed、isPrintWhenDetailOverflows 等属性极其敏感。
立即学习“Java免费学习笔记（深入）”；
- 表格（
<table></table>）必须包裹在<band></band>内，且该 band 的height不能小于表格最小行高总和 - 禁用自动分页：在
<reportelement></reportelement>上设isSplitAllowed="false"，但会导致内容溢出——更稳妥的是设isFloatColumnFooter="true"配合isPrintRepeatedValues="false" - PDF 导出器默认启用压缩，有时会破坏字体嵌入，可临时关闭：
pdfExporter.setParameters(Collections.singletonMap(JRExporterParameter.IS_COMPRESSED, false))
