Loki可视化测试本地正常但GitHub Actions执行失败求助

1. 确保参考图正确同步到CI环境 #

• 检查.loki/reference目录是否已加入Git追踪并推送到远程仓库，若未执行过，运行git add .loki/reference后提交推送。
• 若用Git LFS存储截图（大文件），需在GitHub Actions工作流中开启LFS支持：

  - name: Checkout code
    uses: actions/checkout@v4
    with:
      lfs: true
  

  或在checkout后手动拉取LFS文件：

  git lfs pull
  

2. 统一CI与本地的运行环境 #

• 配置虚拟显示（Linux CI必填）：Linux无头环境需要Xvfb模拟图形界面，在工作流中添加：

  sudo apt-get update && sudo apt-get install -y xvfb
  Xvfb :99 -screen 0 1280x1024x24 &
  export DISPLAY=:99
  

• 固定浏览器版本：在package.json中指定puppeteer版本，避免CI与本地浏览器差异：

  "devDependencies": {
    "puppeteer": "21.5.2"
  }
  

• 统一视口配置：在loki.config.js中设置一致的屏幕分辨率：

  module.exports = {
    viewports: {
      mobile: { width: 375, height: 667 },
      desktop: { width: 1280, height: 720 },
    },
  };
  

3. 调整截图匹配容忍度 #

• 针对细微渲染差异（如字体抗锯齿、阴影），全局调整匹配阈值：

  module.exports = {
    diffing: {
      threshold: 0.1, // 0-1区间，值越大容忍度越高
    },
  };
  

• 为特定组件单独设置阈值：

  export default {
    title: 'Components/Button',
    parameters: {
      loki: { diffingThreshold: 0.2 },
    },
  };
  

4. 规范CI中Storybook的构建与启动流程 #

• 不要依赖本地构建的storybook-static，需在CI中重新构建并等待服务完全启动：

  steps:
    - name: Install dependencies
      run: npm install
    - name: Build Storybook
      run: npm run build-storybook
    - name: Start Storybook
      run: npm run storybook -- --no-open &
    - name: Wait for Storybook to be ready
      run: npx wait-on http://localhost:6006
    - name: Run Loki tests
      run: npm run loki test
  

5. 正确生成CI环境的基准参考图 #

• 首次在CI运行时，先生成基准参考图并推送：
  1. 在CI工作流中执行npm run loki capture生成参考图
  2. 将.loki/reference目录提交推送到仓库
  3. 后续运行npm run loki test进行对比（避免使用本地生成的参考图，消除环境差异）

内容的提问来源于stack exchange，提问作者Кумар Жекшенбек уулу