开源脑图工具导出PDF时中文乱码如何解决？

Question

常见问题：使用开源脑图工具（如XMind、MindNode开源替代品Freeplane、或基于Electron的Markmap、Minder）导出PDF时，中文标题、节点文字显示为方块或乱码。根本原因多为嵌入字体缺失——PDF导出引擎（如Puppeteer、jsPDF或JavaFX WebView）默认未加载中文字体，且CSS中未显式指定支持中文的`@font-face`或`font-family`（如`"Noto Sans CJK SC", "Microsoft YaHei", sans-serif`）。部分工具依赖系统字体但Linux/macOS未配置中文字体路径，或Windows下字体名编码不兼容。此外，HTML-to-PDF转换时若未设置`<meta />`或文档编码非UTF-8，亦会加剧乱码。该问题在离线导出、CI/CD自动化生成场景中尤为突出，影响技术文档、教学脑图等中文场景的交付质量。

Answer 1

一、现象层：中文PDF导出乱码的典型表现

• XMind 2023（Linux版）导出PDF后，所有层级节点文字均显示为“□□□”；
• Freeplane 1.10.0 在 macOS Monterey 上使用“导出为PDF（via JavaFX WebView）”时，标题正常但子节点中文全为方块；
• Markmap CLI（v0.16.0）执行 markmap input.md --pdf output.pdf 后，PDF中仅英文可见，中文全部丢失；
• Minder（Electron 25 + Chromium 116）在CI流水线中headless导出PDF，日志无报错但生成文件含大量字符；
• 同一份.mind文件，在Windows本地导出正常，但部署到Ubuntu 22.04 Docker容器后即失效。

二、机制层：PDF字体渲染链路中的五处断裂点

下图展示了从脑图DOM → PDF字形输出的关键路径及易故障环节：

graph LR A[脑图HTML结构] --> B[CSS font-family声明] B --> C[WebFont加载/系统字体回退] C --> D[HTML-to-PDF引擎解析
（Puppeteer/jsPDF/JavaFX WebView）] D --> E[PDF嵌入字体策略
（subsetting? full embed? fallback?）] E --> F[PDF阅读器渲染
（Adobe Reader / Preview / Evince）] classDef fault fill:#ffebee,stroke:#f44336; class C,E fault;

三、根因层：跨平台字体生态的结构性失配

平台	默认中文字体路径	PDF引擎可访问性	典型失败场景
Windows	C:\Windows\Fonts\msyh.ttc	Chromium可识别字体名“Microsoft YaHei”，但Puppeteer --font-render-hinting=none会禁用Hinting导致CJK模糊/截断	字体名含空格或括号时CSS引用失败：font-family: "Microsoft YaHei UI" → 解析为两个独立family
macOS	/System/Library/Fonts/PingFang.ttc	JavaFX WebView不读取Core Text字体注册表，需显式-Dprism.font.loadSystemFonts=true	Freeplane启动JVM未加字体参数，且未配置~/.fonts.conf映射
Linux	/usr/share/fonts/opentype/noto/NotoSansCJKsc-Regular.otf	Puppeteer headless模式默认禁用字体配置，需挂载--font-path=/usr/share/fonts并调用fc-cache -fv	Docker镜像基于alpine，缺少fontconfig+ttf-noto-cjk包，fc-list返回空

四、验证层：快速定位故障环节的诊断清单

1. 检查HTML源码是否含 <meta charset="UTF-8"> 及 <meta name="viewport" content="width=device-width, initial-scale=1">；
2. 在DevTools → Elements中右键节点 → “Computed” → 查看font-family实际生效值与font-size是否被重置；
3. 运行 puppeteer.launch({ args: ['--dump-dom'] }) 获取渲染前DOM，比对中文文本是否存在；
4. 用pdfinfo -meta output.pdf查看Embedded Fonts字段是否为空或仅含Helvetica；
5. 在目标环境执行 fc-list | grep -i chinese（Linux/macOS）或 Get-Font | ? Name -like "*yahei*"（PowerShell）确认字体可用性。

五、解法层：生产级中文PDF导出的四维加固方案

针对不同工具链提供可落地的修复模式：

• Markmap/Minder（Electron+Puppeteer）：在main.js中注入自定义font-face，并预加载Noto Sans CJK SC：
  const fontCSS = `@font-face { font-family: 'NotoSansCJK'; src: url('assets/NotoSansCJKsc-Regular.woff2') format('woff2'); } body { font-family: 'NotoSansCJK', sans-serif; }`;
• Freeplane（JavaFX WebView）：修改freeplane.sh添加JVM参数：
  -Dprism.font.loadSystemFonts=true -Dprism.text=t2k -Dprism.order=es2,sw，并在stylesheets/default.css中强制声明font-family: "Noto Sans CJK SC", "PingFang SC", "Microsoft YaHei";
• CI/CD流水线（Docker）：基础镜像必须包含：
  RUN apt-get update && apt-get install -y fonts-noto-cjk ttf-wqy-zenhei fontconfig && fc-cache -fv，并确保Puppeteer启动时传入--font-path=/usr/share/fonts。