如何解决CI环境中Puppeteer下载chrome-headless-shell间歇性失败问题

从错误日志里的Z_BUF_ERROR（unexpected end of file）可以判断，问题本质是下载的chrome-headless-shell压缩包不完整，解压到一半时数据中断，间歇性出现说明是网络或CI环境的不稳定因素导致的。以下是针对性的解决方案：

解决方案 #

1. 跳过自动下载，复用系统预装的Chrome #

AWS CodeBuild部分官方镜像（比如aws/codebuild/standard:7.0及以上）已经预装了Chrome浏览器，直接复用即可：

• 在CodeBuild的环境变量中添加：

  PUPPETEER_SKIP_DOWNLOAD=true
  PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome-stable
  

  这样完全避免了下载步骤，从根源解决问题。

2. 增加下载重试次数 #

Puppeteer默认下载重试3次，调高重试次数可以提升不稳定网络下的成功率：

• 添加环境变量：

  PUPPETEER_DOWNLOAD_RETRIES=5
  

  可以根据实际情况调整到5-10次。

3. 配置pnpm缓存复用 #

你使用的是pnpm，在CodeBuild中缓存pnpm-store可以避免重复下载依赖和浏览器包：

• 在buildspec.yml中添加缓存配置：

  cache:
    paths:
      - 'common/temp/pnpm-store/**/*'
  

  后续构建会直接复用缓存中的文件，减少下载次数。

4. 切换下载源 #

默认下载源（Google CDN）在AWS环境下可能存在访问波动，切换到更稳定的镜像源：

• 添加环境变量使用国内镜像：

  PUPPETEER_DOWNLOAD_HOST=https://npm.taobao.org/mirrors
  

  若有公司内部镜像源，也可以配置对应地址。

5. 检查CodeBuild网络配置 #

• 确保构建项目所在的VPC/子网有稳定的外部网络访问权限，避免安全组/NACL限制出站流量；
• 若使用私有子网，需配置NAT网关保证外部访问的稳定性。

补充说明 #

本地环境稳定是因为网络环境更可控，而CI环境可能存在带宽竞争、网络波动等问题，建议组合使用上述方案（比如重试+缓存+切换源），能最大程度降低失败概率。

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