简介：这是一份面向Java开发者、技术文档工程师及自动化工具开发者的轻量级Markdown转PDF工具库，解决日常技术文档、API说明或学习笔记需快速生成可打印PDF版本的痛点。资源包共24个文件，含15个核心Java源码（实现解析、渲染与导出逻辑）、2个Shell脚本（用于本地构建与测试）、2个XML配置文件（Maven依赖与项目结构定义）、1个YAML（CI集成配置）及LICENSE、README等辅助文件，整体仅40KB，结构精简，便于快速集成与二次开发。已有2404人学习下载，适合希望在Java生态中嵌入Markdown文档自动化输出能力的中初级开发者。读者可直接复用其流畅API完成自定义样式PDF生成，参考完整Maven依赖配置、持续集成脚本及模块化源码组织方式，快速理解多库协同（如Markdown解析器与PDF渲染引擎）的整合设计思路。
1. Markdown2Pdf：用 Java 把 .md 文件秒转 PDF，不依赖浏览器、不调远程服务、纯本地跑通的轻量方案
你有没有试过在 Java 项目里加个「导出文档」按钮，点一下就把用户写的 Markdown 笔记生成 PDF 下载？不是靠前端调 Puppeteer 渲染再传回后端，也不是扔给某云文档 API 等回调——而是真正在 JVM 进程里，用几行代码、零外部进程、无网络依赖，把README.md变成README.pdf？Markdown2Pdf 就是干这个的。它不是封装 wkhtmltopdf 的壳，也不基于 JavaFX WebView（那个在 Docker 容器里默认挂掉），而是用 Flying Saucer + iText7 做底层渲染引擎，把 Markdown 先解析成 XHTML，再用 CSS 控制排版，最终输出语义清晰、分页可控、中文字体可嵌入的 PDF。适合做内部知识库导出模块、课程讲义批量生成、自动化报告流水线——尤其当你被要求「不能开浏览器、不能连外网、PDF 要能打印不糊字」时，这个库是少数几个真能落地的 Java 原生方案。我把它用在某高校实验平台的报告生成功能里，单机 QPS 30+，平均耗时 180ms/页，全程无 GC 尖刺。
2. 核心原理与选型依据：为什么不用 Thymeleaf + wkhtmltopdf，而选 Flying Saucer + CommonMark？
2.1 渲染链路拆解：从 .md 字符串到 PDF 字节流的四步闭环
Markdown2Pdf 的转换不是黑匣子，它走的是「文本 → AST → XHTML → PDF」的确定性路径，每一步都可拦截、可调试、可替换：
- Markdown 解析层：使用
commonmark-java（v0.22.0+）作为解析器，将原始.md文本构建成标准 CommonMark AST。它比老牌 pegdown 更轻、更规范、对 GFM 扩展（如表格、任务列表）支持更稳，且无反射类加载风险（pegdown 在 JDK17+ 上会报InaccessibleObjectException）； - HTML 渲染层：通过自定义
HtmlRenderer将 AST 转为 XHTML 片段，关键点在于：所有标签闭合严格（<br>→<br/>）、无内联 JS/CSS、保留语义结构（<h1>不降级为<div class="h1">），这是后续 CSS 排版的基础； - XHTML → PDF 渲染层：交由
Flying Saucer（rev. 9.1.22）处理，它把 XHTML 当作 XML 解析，用 CSS2.1 子集控制布局，支持@page、break-before、-fs-page-break-inside: avoid等印刷级指令； - 字体与 PDF 输出层：
iText7（v7.2.5）接管最终渲染，负责嵌入中文字体（如 Noto Sans CJK SC）、设置 PDF/A 兼容元数据、添加书签（TOC）、控制页眉页脚——这步决定了 PDF 打印是否糊、搜索是否可选中、目录能否点击跳转。
提示：整个链路不启动任何
ProcessBuilder，不 fork 浏览器进程，不依赖系统字体缓存。所有资源（CSS、字体文件）均可打包进 JAR 或从 classpath 加载，满足离线部署场景。
2.2 对比主流方案：为什么放弃 Thymeleaf + wkhtmltopdf 组合？
| 方案 | 启动开销 | 中文支持 | Docker 可用性 | 分页控制粒度 | 可调试性 |
|---|---|---|---|---|---|
| Thymeleaf 模板 + wkhtmltopdf | 高（每次调用 spawn 新进程） | 弱（需手动指定 --font-outline） | 差（容器需预装 Xvfb + wkhtmltopdf） | 粗（仅支持<body>级 break） | 低（错误日志在 stderr，难定位 HTML 源） |
| JavaFX WebView（JDK8） | 中（WebView 初始化慢） | 中（依赖系统字体） | 极差（Docker 默认无 GUI stack） | 中（需 JS 注入 page-break） | 中（可调试 DOM，但 Java 层不可控） |
| Markdown2Pdf（Flying Saucer + iText7） | 低（全内存操作） | 强（字体文件直嵌） | 高（纯 JAR，无系统依赖） | 细（CSS 级page-break-after: always） | 高（XHTML 可 log，CSS 规则可复现） |
某跨平台系统曾用 Thymeleaf + wkhtmltopdf 导出 200 页实验报告，结果在 Kubernetes Pod 里因缺少/dev/shm导致 wkhtmltopdf crash；换成 Markdown2Pdf 后，同一份模板在相同资源配置下稳定运行 6 个月，GC 时间下降 92%。
2.3 依赖版本锁定：避免 iText7 与 Flying Saucer 的 ClassLoader 冲突
Flying Saucer 旧版（r8）依赖 iText 2.x，而新版（r9+）已切到 iText7，但二者包名不同（com.lowagie.textvscom.itextpdf.kernel），若项目中已引入 iText5，则必须排除冲突：
<!-- Maven pom.xml --> <dependency> <groupId>org.xhtmlrenderer</groupId> <artifactId>flying-saucer-pdf-itext5</artifactId> <version>9.1.22</version> <exclusions> <exclusion> <groupId>com.itextpdf</groupId> <artifactId>itextpdf</artifactId> </exclusion> <exclusion> <groupId>com.itextpdf</groupId> <artifactId>itext-asian</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>com.itextpdf</groupId> <artifactId>kernel</artifactId> <version>7.2.5</version> </dependency> <dependency> <groupId>com.itextpdf</groupId> <artifactId>layout</artifactId> <version>7.2.5</version> </dependency>注意：
flying-saucer-pdf-itext5是官方命名，但它实际绑定的是 iText7，名称未更新是历史包袱。若误引flying-saucer-pdf（旧版），会拉入 iText2，导致java.lang.NoClassDefFoundError: com/lowagie/text/Document。
3. 快速上手：三步集成，从 Hello World 到生产就绪
3.1 最小可行代码：5 行完成基础转换
以下代码无需任何配置文件、不创建临时目录、不写磁盘，直接将字符串转为 PDF 字节数组：
import org.commonmark.node.Document; import org.commonmark.parser.Parser; import org.commonmark.renderer.html.HtmlRenderer; import org.xhtmlrenderer.simple.XhtmlRenderer; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; public class MinimalConverter { public static byte[] mdToPdf(String markdown) throws Exception { // Step 1: Parse markdown to AST Parser parser = Parser.builder().build(); Document document = parser.parse(markdown); // Step 2: Render AST to XHTML (strict, no scripts) HtmlRenderer renderer = HtmlRenderer.builder() .escapeHtml(false) .softbreak("<br/>") .build(); String xhtml = renderer.render(document); // Step 3: Convert XHTML to PDF bytes ByteArrayOutputStream out = new ByteArrayOutputStream(); XhtmlRenderer.getInstance().render( new ByteArrayInputStream(xhtml.getBytes("UTF-8")), out, "UTF-8" ); return out.toByteArray(); } }逻辑说明：
XhtmlRenderer.getInstance()是 Flying Saucer 提供的单例，内部已预设好基础 CSS（如body { font-family: sans-serif; }）。render()方法接受InputStream和OutputStream，全程内存操作，无文件 IO。参数"UTF-8"指定输入编码，必须与 XHTML 声明一致（否则中文乱码）。
3.2 生产级配置：嵌入中文字体、控制页边距、生成目录
真实场景需要更多控制：PDF 要能打印、要带页眉页脚、要支持中文标题、要自动生成书签。以下代码展示如何注入自定义 CSS、注册中文字体、启用 TOC：
import com.itextpdf.kernel.font.PdfFont; import com.itextpdf.kernel.font.PdfFontFactory; import com.itextpdf.kernel.pdf.PdfDocument; import com.itextpdf.layout.Document; import com.itextpdf.layout.element.AreaBreak; import com.itextpdf.layout.element.Div; import com.itextpdf.layout.properties.HorizontalAlignment; import org.xhtmlrenderer.pdf.ITextRenderer; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Paths; public class ProductionConverter { public static byte[] mdToPdfWithStyle(String markdown, String fontPath) throws Exception { // 1. Parse & render to XHTML (same as before) Parser parser = Parser.builder().build(); Document doc = parser.parse(markdown); String xhtml = HtmlRenderer.builder() .escapeHtml(false) .softbreak("<br/>") .build() .render(doc); // 2. Prepare Flying Saucer renderer with custom CSS and font ITextRenderer renderer = new ITextRenderer(); // Inject custom CSS for print layout String css = "@page { margin: 2cm; } " + "h1 { break-before: always; } " + "body { font-family: 'Noto Sans CJK SC'; }"; renderer.getSharedContext().setUserAgentCss(css); // 3. Register Chinese font (must be TrueType/TTF) PdfFont font = PdfFontFactory.createFont(Paths.get(fontPath).toUri(), "UTF-8"); renderer.getFontResolver().addFont(fontPath, "Noto Sans CJK SC", true); // 4. Render to PDF with TOC enabled ByteArrayOutputStream out = new ByteArrayOutputStream(); renderer.setDocumentFromString(xhtml); renderer.layout(); renderer.createPDF(out); return out.toByteArray(); } }参数说明：
fontPath：指向本地 TTF 文件路径（如src/main/resources/fonts/NotoSansCJKsc-Regular.ttf），必须是 TrueType 格式，OpenType（.otf）不支持；break-before: always：强制每个<h1>开新页，避免标题被截断；renderer.getFontResolver().addFont(...)：注册字体别名，XHTML 中font-family: 'Noto Sans CJK SC'才能命中；renderer.createPDF(out)：内部调用 iText7 生成 PDF，自动嵌入字体子集（只含文档中出现的汉字），减小体积。
3.3 Spring Boot 集成：暴露 REST 接口，支持多格式导出
在 Spring Boot 项目中，可将其封装为 Controller，支持POST /api/export/pdf接收 Markdown 字符串并返回 PDF：
@RestController @RequestMapping("/api/export") public class ExportController { private final FontManager fontManager; // 自定义字体管理器，预加载字体 public ExportController(FontManager fontManager) { this.fontManager = fontManager; } @PostMapping(value = "/pdf", produces = MediaType.APPLICATION_PDF_VALUE) public ResponseEntity<byte[]> exportPdf(@RequestBody String markdown) throws Exception { byte[] pdfBytes = ProductionConverter.mdToPdfWithStyle( markdown, fontManager.getNotoSansCjkScPath() // 返回 TTF 文件绝对路径 ); HttpHeaders headers = new HttpHeaders(); headers.setContentDispositionFormData("attachment", "document.pdf"); headers.setContentLength(pdfBytes.length); return ResponseEntity.ok() .headers(headers) .body(pdfBytes); } }关键点：
FontManager应在 Spring Context 初始化时预加载字体路径，避免每次请求都读磁盘。推荐用ResourceUtils.getFile("classpath:fonts/NotoSansCJKsc-Regular.ttf")获取路径，确保打包进 JAR 后仍可访问。
4. 避坑指南：五个真实翻车现场与血泪修复方案
4.1 现象：PDF 中文显示为方块，英文正常
原因：Flying Saucer 默认字体不支持中文，且addFont()未正确注册或字体路径错误。常见于：① 使用.otf字体（Flying Saucer 仅支持.ttf）；② 字体文件权限不足（Linux 容器中chmod 644缺失）；③ CSS 中font-family名称与addFont()第二个参数不一致（如注册为"Noto Sans CJK SC"，但 CSS 写成"NotoSansCJKsc"）。
解决：用FontFactory.register()验证字体是否加载成功：
System.out.println(FontFactory.getRegisteredFonts()); // 查看输出是否含目标字体名若无，则检查 TTF 文件头（file font.ttf应输出TrueType font data），并确认addFont(path, "Noto Sans CJK SC", true)的 family name 与 CSS 完全一致。
4.2 现象：表格内容被截断，列宽异常
原因：CommonMark 默认表格渲染为<table>，但 Flying Saucer 对<table>的width: 100%支持不完整，且未设置table-layout: fixed。
解决：在自定义 CSS 中强制声明：
table { table-layout: fixed; width: 100%; } td, th { word-break: break-word; }并在HtmlRenderer构建时禁用table的自动宽度计算：
HtmlRenderer.builder() .attributeProvider((node, attributes) -> { if (node instanceof Table) { attributes.put("style", "table-layout:fixed;width:100%"); } }) .build();4.3 现象：PDF 页眉页脚不显示，或位置偏移
原因：Flying Saucer 的@pageCSS 规则需配合margin和padding精确控制，且页眉页脚必须用<div class="header">/<div class="footer">并在 CSS 中用position: running(header)定义。
解决：在 XHTML 渲染前注入页眉页脚 div，并在 CSS 中定义：
String xhtmlWithHeader = "<div class=\"header\">Report v1.0</div>" + xhtml + "<div class=\"footer\">Page <span class=\"page-number\"></span></div>"; // CSS: // @page { @top-center { content: element(header); } @bottom-center { content: element(footer); } } // .header { position: running(header); } // .footer { position: running(footer); } // .page-number:after { content: counter(page); }4.4 现象：超长代码块横向滚动条失效，内容溢出页面
原因：<pre><code>默认white-space: pre，Flying Saucer 不支持overflow-x: auto，且 PDF 不渲染滚动条。
解决：CSS 中强制换行并添加背景：
pre code { white-space: pre-wrap; word-break: break-all; background-color: #f5f5f5; padding: 8px; }同时在HtmlRenderer中为代码块添加class="highlight"，便于 CSS 精准匹配。
4.5 现象：生成 PDF 后内存泄漏，堆内存持续增长
原因：ITextRenderer实例未复用，每次新建导致FontResolver缓存字体对象不释放；或ByteArrayOutputStream未及时 close（虽不影响功能，但阻碍 GC）。
解决：全局单例ITextRenderer，并重置上下文：
private static final ITextRenderer RENDERER = new ITextRenderer(); // 使用前重置 RENDERER.getSharedContext().reset(); RENDERER.getFontResolver().reset(); RENDERER.setDocumentFromString(xhtml);避免在循环中new ITextRenderer()。
5. 进阶技巧：动态样式注入、分页锚点、PDF/A 合规与性能压测
5.1 动态 CSS 注入：根据用户角色切换 PDF 主题
业务常需「学生版 PDF 无答案，教师版 PDF 含解析」。与其维护两套 Markdown，不如在渲染时动态注入 CSS 类：
public byte[] mdToPdfByRole(String markdown, String role) throws Exception { String xhtml = renderToXhtml(markdown); // 注入 role-specific class to <body> xhtml = xhtml.replaceFirst("<body>", "<body class=\"" + role + "\">"); ITextRenderer renderer = getSharedRenderer(); renderer.getSharedContext().setUserAgentCss( ".student .answer { display: none; }" + ".teacher .hint { color: #666; font-style: italic; }" ); // ... render }逻辑：
<div class="answer">在学生版中被 CSS 隐藏，教师版中可见。无需修改原始 Markdown，样式与内容彻底解耦。
5.2 分页锚点与书签：让 PDF 目录可点击跳转
Flying Saucer 原生支持id属性生成书签，但需确保<h1 id="section1">格式正确。以下代码自动为所有标题添加唯一 ID：
public String addHeadingIds(String markdown) { return markdown.replaceAll("(^#{1,6}\\s+)(.+)$", "$1<span id=\"h-$2\"></span>$2"); } // 生成 ID 规则：h-Introduction → h-Getting-Started // CSS 中可加：#h-Introduction { break-before: page; }效果：PDF 左侧导航栏自动生成层级书签，点击即跳转。
break-before: page确保每个章节独占一页。
5.3 PDF/A-1b 合规：满足归档长期保存要求
某些政务/教育系统强制 PDF/A-1b 标准（嵌入所有字体、禁止加密、元数据完整）。iText7 可开启合规模式：
PdfWriter writer = new PdfWriter(out); PdfDocument pdfDoc = new PdfDocument(writer); pdfDoc.getCatalog().setPdfAConformance(PdfAConformance.PDF_A_1B); // 设置元数据 pdfDoc.getDocumentInfo() .setTitle("Lab Report") .setAuthor("System") .setCreator("Markdown2Pdf v1.0"); // 注册字体时必须用 embed=true PdfFont font = PdfFontFactory.createFont(fontPath, PdfEncodings.IDENTITY_H, true);注意：PDF/A 要求所有字体必须嵌入（
true参数），且不能使用Helvetica等 Base14 字体（需显式替换为 Noto Sans）。
5.4 性能压测与调优：单线程 vs 多线程吞吐对比
我在某模拟项目 X 中做了基准测试（JDK17, 16GB RAM, Markdown 平均 800 行）：
| 并发数 | 单线程实例（复用 renderer） | 每线程新建 renderer | P95 延迟 | CPU 使用率 |
|---|---|---|---|---|
| 1 | 120 ms | 180 ms | 120 ms | 35% |
| 10 | 135 ms | 320 ms | 180 ms | 68% |
| 50 | 160 ms | OOM（Metaspace） | 310 ms | 92% |
结论：必须复用ITextRenderer实例，且建议用ThreadLocal<ITextRenderer>隔离线程状态：
private static final ThreadLocal<ITextRenderer> RENDERER_TL = ThreadLocal.withInitial(() -> { ITextRenderer r = new ITextRenderer(); r.getSharedContext().setUserAgentCss(BASE_CSS); r.getFontResolver().addFont(NOTO_SANS_PATH, "Noto Sans CJK SC", true); return r; });从那以后我每次初始化
ITextRenderer都强制走一遍getSharedContext().reset()和getFontResolver().reset()，哪怕用了ThreadLocal—— 曾因某次 CSS 注入未重置，导致第 37 个请求的页眉错用第 12 个请求的样式，排查了整整一个下午。希望帮到你。
本文还有配套的精品资源，点击获取
