MarkdownPoster导出PDF时中文乱码如何解决？

Question

**问题描述（198词）：** 使用 MarkdownPoster（基于 Puppeteer + Chromium 的 Markdown 转 PDF 工具）导出含中文的 Markdown 文档时，生成的 PDF 中文字显示为方框、空白或乱码（如“□□□”），但原文本在浏览器预览中正常。该问题并非源码编码错误（UTF-8 已正确声明），而是 Chromium 渲染引擎在无字体上下文的 Headless 模式下默认不加载系统中文字体（如 Noto Sans CJK、思源黑体、微软雅黑等）。MarkdownPoster 默认未配置字体映射或自定义 `--font-render-hinting=none` 等渲染参数，且其底层 Puppeteer 实例未显式注入 `@font-face` 或设置 `pdfOptions.format`/`pdfOptions.displayHeaderFooter` 相关字体上下文。此外，Linux/macOS 服务器环境常缺失中文字体包，Docker 镜像若基于 `puppeteer:latest`（精简版 Chromium）亦默认剥离 CJK 字体支持。临时规避（如改用英文导出）不可行于本地化交付场景。根本原因在于：PDF 导出链路（Markdown → HTML → Chromium 渲染 → PDF）中，HTML 层虽含中文，但 Chromium 无法回退到可用中文字体，导致 glyph 缺失。需从字体注入、Puppeteer 启动参数、系统字体安装及 CSS font-family 显式声明四方面协同解决。

Answer 1

```html

一、现象定位：PDF 中文乱码的表层表现

• MarkdownPoster 导出含中文的 Markdown 文档时，PDF 中文字显示为方框（□）、空白或乱码；
• 同一文档在 Chromium 浏览器中预览正常，证明源码 UTF-8 编码无误、HTML 结构完整；
• 问题复现稳定于 Linux/macOS 服务器及 Docker 容器环境，Windows 本地偶有正常（依赖系统预装微软雅黑）；
• 控制台无 JS 报错，Network 面板确认 CSS/字体资源未被阻断，但 DevTools → Elements → Computed 中 font-family 显示为 fallback（如 "sans-serif"），且实际渲染 glyph 为空。

二、链路剖析：四层渲染断点诊断

PDF 生成本质是「Markdown → HTML → Chromium 渲染 → PDF」的端到端流水线，各环节字体上下文缺失如下：

层级	关键断点	典型证据
Markdown → HTML	未注入 @font-face 或内联 base64 字体	CSS 中仅声明 font-family: "Noto Sans CJK SC"，但未提供字体源
Puppeteer 启动	Chromium Headless 模式未加载系统字体缓存	getAvailableFonts() 返回空数组（需通过 chrome://settings/fonts 验证）

三、根因深挖：Chromium 的字体回退机制失效

Headless Chromium 默认禁用 FontConfig / Core Text 字体发现逻辑，且不读取 /etc/fonts/conf.d/ 或 ~/Library/Fonts。即使系统已安装 Noto Sans CJK，Puppeteer 实例启动时若未显式传入 --font-render-hinting=none 和 --disable-font-subpixel-positioning，glyph rasterization 将跳过 CJK fallback chain，直接使用 ASCII-only 字体（如 DejaVu Sans）渲染中文字符——导致 □□□。

四、协同解决方案（四维加固）

1. 系统层：Linux 容器内安装开源中文字体：
   apt-get update && apt-get install -y fonts-noto-cjk fonts-wqy-zenhei
2. CSS 层：在 HTML 模板中嵌入 @font-face 声明（推荐 WOFF2 base64 内联，规避 CORS）：

@font-face {
  font-family: 'NotoSansCJK';
  src: url('data:font/woff2;base64,d09GMgABAAAAA...') format('woff2');
  font-weight: 400;
  font-style: normal;
}

五、Puppeteer 运行时增强配置

启动 Chromium 时必须启用以下参数（缺一不可）：

• --no-sandbox（容器必需）
• --font-render-hinting=none（禁用 hinting 提升 CJK 渲染一致性）
• --disable-font-subpixel-positioning（避免 subpixel 错位导致字形截断）
• --disable-gpu（部分服务器 GPU 驱动缺失引发字体 cache 失效）

六、验证闭环：可量化的成功指标

部署后执行以下检查项，全部通过即确认修复：

1. PDF 中文字符宽度均匀，无横向压缩/拉伸；
2. 使用 pdfinfo -meta output.pdf | grep "Title\|Creator" 确认元数据含中文；
3. 用 pdffonts output.pdf 输出非-empty 字体列表（含 NotoSansCJK-Regular）；
4. 在 headless Chrome 中打开生成的 HTML，DevTools → Application → Fonts 显示已加载目标字体。

七、Docker 最佳实践（生产就绪）

基于官方 puppeteer:latest 构建镜像时，务必扩展字体支持：

FROM ghcr.io/puppeteer/puppeteer:latest
RUN apt-get update && \
    apt-get install -y fonts-noto-cjk ttf-wqy-zenhei && \
    fc-cache -fv

并确保 Puppeteer launch() 调用中指定 executablePath 与容器内 Chromium 一致。

八、进阶防御：动态字体注入中间件

针对多语言 SaaS 场景，建议在 Markdown 渲染前注入智能字体策略：

graph LR A[Markdown Source] --> B{Language Detect} B -->|zh-CN| C[Inject NotoSansCJK + woff2] B -->|ja-JP| D[Inject NotoSansCJK + Japanese subset] B -->|ko-KR| E[Inject NotoSansCJK + Korean subset] C --> F[Render HTML] D --> F E --> F F --> G[Puppeteer PDF Export] ```