React格式转换项目求助：MD转PDF实现方案及空白输出问题

一、现成工具/库推荐 #

• Marked + Puppeteer：最常用的组合，先用 Marked 将 MD 转成 HTML，再通过 Puppeteer 无头浏览器渲染 HTML 并导出 PDF，多数文档导出类项目都采用这套流程。
• md-to-pdf：封装好的 Node.js 工具，内部基于 Marked 和 Puppeteer 实现，可直接在后端服务或 Electron 环境中调用，省去手动拼接流程的工作量。
• react-markdown + React-PDF：前端直接生成方案，先用 react-markdown 将 MD 转成 React 元素，再通过 React-PDF 的组件体系渲染生成 PDF，适合轻量需求场景。

二、空白PDF问题排查与解决 #

你遇到的空白输出，核心原因多为渲染时机、内容处理或配置问题，对应解决方法如下：

1. 异步内容未等待加载：若 MD 包含图片、异步渲染组件，直接导出会因内容未加载完成导致空白。用 Puppeteer 时需设置 waitUntil: 'networkidle0'；用 React-PDF 时，需确保所有异步内容加载完成后再触发导出。
2. 缺失基础样式：MD 转 HTML 后未注入样式，可能出现文字与背景色一致、布局错乱等情况。导出前需添加基础样式，示例：

<style>
  body { font-family: Arial, sans-serif; color: #333; padding: 20px; }
  h1, h2 { border-bottom: 1px solid #eee; margin: 16px 0; }
  code { background: #f5f5f5; padding: 2px 4px; border-radius: 4px; }
</style>

3. MD 转换失败：先检查 MD 转 HTML/React 元素的结果是否为空或存在语法错误，可在控制台打印转换产物，确认内容正常后再执行导出。
4. Puppeteer 配置遗漏：使用 Puppeteer 时，需开启 printBackground: true（否则背景色、图片可能不显示），同时设置合适的页面尺寸与边距，避免内容被裁剪。

示例代码 #

Marked + Puppeteer 后端方案

const marked = require('marked');
const puppeteer = require('puppeteer');

async function mdToPdf(mdContent) {
  const html = `
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8">
        <style>
          body { font-family: 'Segoe UI', sans-serif; padding: 30px; max-width: 800px; margin: 0 auto; }
          pre { background: #f8f9fa; padding: 15px; border-radius: 6px; overflow-x: auto; }
        </style>
      </head>
      <body>
        ${marked.parse(mdContent)}
      </body>
    </html>
  `;

  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.setContent(html, { waitUntil: 'networkidle0' });
  const pdfBuffer = await page.pdf({
    format: 'A4',
    printBackground: true,
    margin: { top: '20mm', right: '15mm', bottom: '20mm', left: '15mm' }
  });
  await browser.close();
  return pdfBuffer;
}

react-markdown + React-PDF 前端方案

import React, { useState } from 'react';
import ReactMarkdown from 'react-markdown';
import { Document, Page, pdf } from '@react-pdf/renderer';

function PdfDocument({ mdContent }) {
  return (
    <Document>
      <Page size="A4" style={{ padding: 20 }}>
        <ReactMarkdown>{mdContent}</ReactMarkdown>
      </Page>
    </Document>
  );
}

export default function MdToPdfConverter() {
  const [mdContent, setMdContent] = useState('# Hello\nThis is a **test** MD content');

  const handleExport = async () => {
    const blob = await pdf(<PdfDocument mdContent={mdContent} />).toBlob();
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'output.pdf';
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div>
      <textarea value={mdContent} onChange={(e) => setMdContent(e.target.value)} rows={10} style={{ width: '100%' }} />
      <button onClick={handleExport}>导出PDF</button>
    </div>
  );
}

注：前端方案对复杂 CSS 支持有限，若需高精度排版，优先选择后端 Puppeteer 方案。

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