Ubuntu环境下Headless Chrome（Puppeteer）无法加载Google字体问题

问题核心原因 #

你在Digital Ocean的Ubuntu 20.04/22.04、Debian 12 Droplet上用Puppeteer截图时，Google字体（Quicksand）和Emoji无法加载，本地Mac正常运行的核心原因是：Linux服务器缺少必要的字体依赖与无头Chrome渲染环境——无桌面环境的服务器默认未预装网页常用字体，Puppeteer自带的无头Chrome无法自动获取这些资源。

分步解决方案 #

1. 安装系统级字体依赖 #

直接在服务器上安装目标字体、基础渲染字体及Emoji字体，执行对应系统的命令：

Ubuntu 20.04/22.04

sudo apt update && sudo apt install -y fonts-liberation fonts-quicksand fonts-noto-color-emoji chromium-browser

Debian 12

sudo apt update && sudo apt install -y fonts-liberation fonts-quicksand fonts-noto-color-emoji chromium

各包作用：

• fonts-liberation：补充基础无衬线字体作为 fallback
• fonts-quicksand：直接安装Quicksand字体，无需依赖网络加载
• fonts-noto-color-emoji：解决Emoji缺失问题
• 系统Chrome/Chromium：确保与Puppeteer的Chrome共享一致的字体环境

2. 调整Puppeteer启动配置 #

修改启动参数，优化字体渲染逻辑，可选指定系统Chrome路径确保环境统一：

const browser = await puppeteer.launch({
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--font-render-hinting=medium',
    '--enable-font-antialiasing',
    '--disable-font-subpixel-positioning'
  ],
  headless: "new",
  defaultViewport: {
    width: 1200,
    height: 630,
    deviceScaleFactor: 2,
  },
  // 可选：指定系统Chrome路径，Ubuntu填/usr/bin/chromium-browser，Debian填/usr/bin/chromium
  // executablePath: '/usr/bin/chromium-browser'
});

3. 确保字体加载完成再截图 #

若必须依赖网络加载字体，替换原等待逻辑为监听浏览器字体加载状态：

await page.goto(url, { waitUntil: "networkidle0" });

// 等待所有字体加载完成并验证目标字体
await page.evaluate(async () => {
  await document.fonts.ready;
  const isQuicksandLoaded = document.fonts.check('12px Quicksand');
  if (!isQuicksandLoaded) throw new Error('Quicksand字体加载失败');
});

const buffer = await page.screenshot({ type: "jpeg", quality: 70 });

4. 备选：注入本地字体文件 #

若网络加载字体不稳定，可将Quicksand的.woff2字体文件上传到服务器，通过Puppeteer直接注入页面：

await page.goto(url, { waitUntil: "domcontentloaded" });

// 注入本地字体
await page.addStyleTag({
  content: `
    @font-face {
      font-family: 'Quicksand';
      src: url('/path/to/your/quicksand.woff2') format('woff2');
      font-weight: normal;
      font-style: normal;
    }
  `
});

await page.waitForNetworkIdle();
const buffer = await page.screenshot({ type: "jpeg", quality: 70 });

验证方法 #

安装完成后，在服务器终端执行以下命令，检查字体是否安装成功：

fc-list | grep Quicksand
fc-list | grep Noto Color Emoji

若输出字体路径，说明安装生效。

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