优先使用 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-collections 3.x）
• 字体渲染问题多源于 jasperreports-fonts 版本不匹配，务必确认它和主包版本一致（例如都用 6.20.0）

模板（.jrxml）编译成 .jasper 时，中文乱码或字体不生效

不是模板写错了，而是编译环节缺失字体注册和编码配置。JasperReports 默认不加载系统字体，也不自动识别 UTF-8 模板文件编码。

• 确保 .jrxml 文件本身保存为 UTF-8 编码（IDE 中检查右下角编码标识）
• 在编译前调用 JRXmlCompiler.compileReport() 前，先执行 JRFontUtil.registerFonts()（需提前加载 jasperreports-fonts JAR）
• 模板中所有 <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。

Java调试

通过 JDWP 实现 Java 远程调试：连接远程 JVM、设置断点、单步执行代码、查看变量值、获取调用栈。适用于需要调试远程 Java 应用、排查运行时状态、追踪代码执行流程的场景。 术语注解 JDWP：Java Debug Wire Protocol，Java 调试有线协议（Java 远程调试底层通信协议） remote JVM：远程 Java 虚拟机 step through code：代码单步调试（步入 / 步过 / 步出调试） inspect variables：变量查看 / 变量检视 stac

下载

• 模板文件放在 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))

JasperReports 的坑基本都在「编译—加载—填充—导出」这四步的衔接处，尤其是字体注册时机、资源路径解析、PDF 分页策略这三个点，改错一个参数就可能让整页变空白。