Puppeteer-Sharp生成PDF时无法识别cursive草书字体如何解决？

Puppeteer-Sharp 完全可以正常使用草书字体实现签名效果，你遇到的字体被忽略的问题，是因为Puppeteer调用的Chromium渲染逻辑和桌面浏览器存在差异，常见遗漏配置如下：

• 确认运行环境的字体安装状态
  你本地桌面浏览器可以正常显示Brush Script MT，是因为你的Windows系统默认预装了该字体，但是如果你的代码部署在Linux、Docker容器等无GUI的环境下，默认不会预装这款Windows专属字体，Chromium找不到对应字体就会自动 fallback 到默认字体。
  你可以通过CSS @font-face 规则直接嵌入字体资源，完全不依赖系统字体配置，示例如下：

  /* 提前把字体文件放到项目可访问的路径下 */
  @font-face {
    font-family: 'Brush Script MT';
    src: url('./static/BrushScriptMT.woff2') format('woff2');
    font-weight: normal;
    font-style: normal;
  }
  .signature { 
    font-family: 'Brush Script MT', cursive; 
  }
  

  如果是部署在Docker容器中，也可以直接把字体文件拷贝到容器的系统字体目录（如/usr/share/fonts），执行fc-cache刷新字体缓存即可。

• 等待字体加载完成后再导出PDF
  Puppeteer默认不会等待所有字体资源加载完成就执行PDF导出逻辑，很可能字体还没加载完成就已经开始渲染PDF，导致字体不生效。你可以在调用PdfStreamAsync之前添加等待字体加载的代码：

  // 等待页面所有字体加载完成
  await page.WaitForFontLoadingAsync();
  // 再执行PDF导出
  var stream = await page.PdfStreamAsync(new PdfOptions
  {
     Format = PaperFormat.A4,
     MarginOptions = new MarginOptions
     {
        Top = "0px",
        Right = "0px",
        Bottom = "0px",
        Left = "0px"
     },
     PrintBackground = true,
  });
  

• 调整Chromium启动参数
  旧版本Puppeteer-Sharp的默认无头模式对自定义字体的渲染存在兼容问题，你可以在启动Browser时添加如下参数优化字体渲染：

  var browser = await Puppeteer.LaunchAsync(new LaunchOptions
  {
      Headless = HeadlessMode.New, // 使用新版无头模式，字体兼容性更好
      Args = new string[] { "--font-render-hinting=none" }
  });
  

• 优化字体 fallback 规则
  如果你不想嵌入字体，可以补充多平台的草书字体作为 fallback，避免单一字体找不到的问题：

  .signature { 
    font-family: 'Brush Script MT', 'Brush Script Std', 'URW Chancery L', cursive; 
  }
  

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