1. 项目背景与核心需求最近在整理技术文档时发现Markdown格式的README和API说明需要转换成PDF格式发给非技术同事。手动复制粘贴到Word再转PDF不仅效率低下格式还经常错乱。于是研究了几种用Java实现Markdown转PDF的方案这里把踩坑经验分享给大家。这个需求在以下场景特别常见需要将GitHub项目的README导出为PDF归档自动化生成技术文档交付物企业知识库系统的文档导出功能博客内容的多格式发布2. 技术方案选型对比2.1 常见技术路线分析目前Java生态中主流的Markdown转PDF方案有以下几种CommonMark PDFBox组合优点纯Java实现依赖少缺点需要手动处理样式开发量大Flexmark OpenHTMLToPDF优点支持最新Markdown语法缺点中文排版需要额外配置PegDown Flying Saucer优点成熟稳定缺点已停止维护使用外部工具调用如Pandoc需要系统安装依赖2.2 推荐方案Flexmark OpenHTMLToPDF经过实际测试我最终选择了Flexmark OpenHTMLToPDF组合原因如下Flexmark支持CommonMark和GitHub Flavored MarkdownOpenHTMLToPDF的PDF渲染质量高中文排版问题可通过字体嵌入解决纯Java实现不依赖外部工具3. 详细实现步骤3.1 环境准备首先在pom.xml中添加依赖dependencies !-- Flexmark核心 -- dependency groupIdcom.vladsch.flexmark/groupId artifactIdflexmark-all/artifactId version0.64.0/version /dependency !-- PDF转换 -- dependency groupIdorg.jsoup/groupId artifactIdjsoup/artifactId version1.15.3/version /dependency dependency groupIdcom.openhtmltopdf/groupId artifactIdopenhtmltopdf-core/artifactId version1.0.10/version /dependency dependency groupIdcom.openhtmltopdf/groupId artifactIdopenhtmltopdf-pdfbox/artifactId version1.0.10/version /dependency /dependencies3.2 核心转换代码实现import com.vladsch.flexmark.html.HtmlRenderer; import com.vladsch.flexmark.parser.Parser; import com.vladsch.flexmark.profile.pegdown.Extensions; import com.vladsch.flexmark.profile.pegdown.PegdownOptionsAdapter; import com.vladsch.flexmark.util.data.DataHolder; import org.jsoup.Jsoup; import org.jsoup.nodes.Document; import java.io.*; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Paths; public class MarkdownToPdfConverter { // 配置Markdown解析选项 private static final DataHolder OPTIONS PegdownOptionsAdapter.flexmarkOptions( Extensions.ALL ); public static void convert(String markdownFile, String pdfFile) throws IOException { // 1. 读取Markdown文件 String markdown new String(Files.readAllBytes(Paths.get(markdownFile)), StandardCharsets.UTF_8); // 2. 转换为HTML Parser parser Parser.builder(OPTIONS).build(); HtmlRenderer renderer HtmlRenderer.builder(OPTIONS).build(); String html renderer.render(parser.parse(markdown)); // 3. 处理HTML结构 Document doc Jsoup.parse(html); doc.outputSettings().syntax(Document.OutputSettings.Syntax.xml); // 4. 转换为PDF try (OutputStream os new FileOutputStream(pdfFile)) { com.openhtmltopdf.pdfbox.PdfRendererBuilder builder new com.openhtmltopdf.pdfbox.PdfRendererBuilder(); builder.withHtmlContent(doc.html(), null); builder.toStream(os); builder.run(); } } }3.3 中文支持配置要让PDF正确显示中文需要添加中文字体支持// 在PdfRendererBuilder后添加字体配置 builder.useFont(new File(fonts/NotoSansSC-Regular.ttf), Noto Sans SC);推荐使用思源黑体(Noto Sans SC)或阿里巴巴普惠体需要将字体文件放在resources/fonts目录下。4. 高级功能实现4.1 自定义CSS样式可以通过以下方式添加自定义样式String css page { size: A4; margin: 1cm; } body { font-family: Noto Sans SC; font-size: 12pt; } code { background: #f5f5f5; padding: 2px 4px; }; builder.withHtmlContent( htmlheadstyle css /style/headbody doc.body().html() /body/html, null );4.2 处理图片嵌入Markdown中的图片需要特殊处理才能正确显示在PDF中// 替换图片路径为绝对路径 Elements imgs doc.select(img); for (Element img : imgs) { String src img.attr(src); if (!src.startsWith(http)) { img.attr(src, new File(markdownFile).getParent() / src); } }4.3 分页与页眉页脚使用CSS控制分页和页眉页脚page { top-left { content: 我的技术文档; font-size: 10pt; } bottom-center { content: counter(page); } } h1 { page-break-before: always; }5. 常见问题与解决方案5.1 中文乱码问题现象PDF中中文显示为方框解决确认已添加中文字体检查字体文件路径是否正确在CSS中明确指定字体族5.2 图片不显示现象PDF中图片位置空白解决使用绝对路径引用图片确认图片文件存在且可读对于网络图片确保URL可访问5.3 列表样式异常现象列表缩进或编号不正确解决添加CSS重置列表样式检查Markdown列表语法是否正确避免混合使用有序和无序列表5.4 代码块换行问题现象代码块中的长行被截断解决pre { white-space: pre-wrap; word-wrap: break-word; }6. 性能优化建议字体子集化只嵌入实际使用的字形减小PDF体积缓存解析器实例Parser和HtmlRenderer可以复用批量处理对多个文件使用同一个PdfRendererBuilder实例异步处理对大量文档使用线程池处理// 缓存解析器实例示例 private static final Parser PARSER Parser.builder(OPTIONS).build(); private static final HtmlRenderer RENDERER HtmlRenderer.builder(OPTIONS).build();7. 替代方案比较方案优点缺点适用场景FlexmarkOpenHTML纯Java、高质量输出配置复杂企业级应用Pandoc调用功能强大、支持多格式依赖外部工具个人使用Thymeleaf PDF整合Spring方便功能有限Spring项目JasperReports报表功能强学习曲线陡复杂报表8. 完整工具类实现以下是经过生产环境验证的完整工具类public class MarkdownPdfUtils { private static final DataHolder OPTIONS PegdownOptionsAdapter.flexmarkOptions( Extensions.ALL ); private static final Parser PARSER Parser.builder(OPTIONS).build(); private static final HtmlRenderer RENDERER HtmlRenderer.builder(OPTIONS).build(); public static void convertToPdf(Path markdownPath, Path pdfPath, Path fontDir) throws IOException { String markdown Files.readString(markdownPath); String html RENDERER.render(PARSER.parse(markdown)); Document doc Jsoup.parse(html); doc.outputSettings().syntax(Document.OutputSettings.Syntax.xml); // 处理图片路径 processImages(doc, markdownPath); // 基础CSS String css buildBasicCss(); try (OutputStream os Files.newOutputStream(pdfPath)) { PdfRendererBuilder builder new PdfRendererBuilder(); builder.withHtmlContent(wrapHtml(doc, css), markdownPath.getParent().toUri().toString()); builder.toStream(os); // 加载字体 loadFonts(builder, fontDir); builder.run(); } } private static void processImages(Document doc, Path markdownPath) { // 实现图片路径处理... } private static String buildBasicCss() { // 返回基础CSS样式... } private static String wrapHtml(Document doc, String css) { // 包装HTML结构... } private static void loadFonts(PdfRendererBuilder builder, Path fontDir) throws IOException { // 加载字体文件... } }实际项目中这个工具类可以进一步扩展支持自定义页眉页脚水印添加文档加密多文档合并9. 测试与验证建议编写单元测试验证转换效果Test public void testConvertMarkdownToPdf() throws Exception { Path mdFile Paths.get(src/test/resources/test.md); Path pdfFile Paths.get(target/test.pdf); Path fontDir Paths.get(src/main/resources/fonts); MarkdownPdfUtils.convertToPdf(mdFile, pdfFile, fontDir); assertTrue(Files.exists(pdfFile)); assertTrue(Files.size(pdfFile) 0); }测试时应检查中文显示是否正确代码块格式是否保留图片是否正常显示超链接是否可用表格边框是否完整10. 部署注意事项字体打包确保字体文件被打包到最终jar中资源路径在生产环境注意文件路径问题内存设置大文档转换需要增加JVM内存依赖冲突注意与项目中其他库的版本兼容性对于Spring Boot项目可以创建自动配置Configuration ConditionalOnClass(Parser.class) public class MarkdownPdfAutoConfiguration { Bean public MarkdownPdfUtils markdownPdfUtils() { return new MarkdownPdfUtils(); } }11. 扩展思路基于这个基础功能还可以实现Web服务暴露REST API提供转换服务批量转换监控目录自动处理新文件邮件附件自动将转换结果作为附件发送文档预览与前端集成实现实时预览例如实现Spring Boot端点RestController RequestMapping(/api/docs) public class DocumentController { PostMapping(/convert) public ResponseEntityResource convertToPdf(RequestBody String markdown) { // 实现转换逻辑... } }12. 经验总结在实际项目中应用这套方案时有几个关键点值得注意字体许可确保使用的字体有合法的授权许可商业项目尤其要注意错误处理对大型文档要做好内存管理和超时控制版本升级关注Flexmark和OpenHTMLToPDF的版本更新样式调试开发阶段可以输出中间HTML辅助调试一个实用的调试技巧是保存中间HTMLFiles.writeString(Paths.get(debug.html), html);这样当PDF输出不符合预期时可以先检查HTML阶段是否正确。