Docker中运行Playwright测试出现字体异常致截图对比失败

核心问题定位 #

CI环境与本地Docker容器的字体环境存在差异，偶发的分片测试通过情况说明字体加载/渲染存在随机性，大概率是CI容器启动后字体缓存未完全就绪，或部分依赖字体缺失导致渲染 fallback 到不同字体。

具体解决步骤 #

• 统一容器字体环境
  在本地生成预期截图的Docker和CI运行的Docker中，安装完全一致的字体包。以Ubuntu/Debian系容器为例，执行：

  apt-get update && apt-get install -y fonts-freefont-ttf fonts-dejavu-core fonts-noto-color-emoji
  

  确保系统字体和应用依赖字体完全同步，避免因字体缺失触发替换逻辑。

• 强制页面使用指定字体
  在测试代码中通过全局CSS强制页面元素使用双方都已安装的字体，消除系统字体差异影响：

  await page.addStyleTag({
    content: `* { font-family: 'DejaVu Sans', sans-serif !important; }`
  });
  

• 预加载CI容器字体缓存
  偶发问题多因容器启动后字体缓存未生成，导致部分测试执行时字体未就绪。在CI脚本开头添加：

  fc-cache -fv
  

  强制刷新字体缓存，确保容器启动后所有字体可立即被调用。

• 禁用Playwright字体自动替换
  在Playwright配置文件中关闭字体相关的自动优化，防止触发意外的字体替换：

  // playwright.config.js
  module.exports = {
    use: {
      launchOptions: {
        args: ['--disable-font-subpixel-positioning', '--disable-font-subpixel-scaling']
      }
    }
  };
  

• 保障分片测试环境一致性
  所有分片测试使用相同的Docker镜像，且每个分片启动前都执行字体缓存刷新步骤，避免不同分片的容器配置存在差异。

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