Puppeteer 在自动化测试、爬虫采集以及前端渲染监控中应用广泛，而 Chromium 下载失败几乎是新环境部署时最常见的问题之一。尤其在 CI/CD、Docker 容器或海外服务器环境中，经常会遇到安装卡住、下载超时或提示 Chromium revision not downloaded 等错误。解决这类问题，需要从网络环境、依赖配置以及缓存机制三个层面系统排查。
在 Puppeteer 的默认安装流程中，npm install puppeteer 会自动下载与版本匹配的 Chromium 浏览器。如果网络环境不稳定，这一步极容易失败，导致后续启动时报错。错误信息通常表现为找不到 executablePath，或者提示浏览器修订版本缺失。
一、网络问题导致 Chromium 下载失败
国内环境是最常见的故障来源。Chromium 官方下载源位于 Google 服务器，在部分网络环境下无法访问，表现为下载卡住或 403/timeout 错误。
解决方式通常有两种思路：
1. 使用国内镜像源
可以通过环境变量指定下载地址：
-
PUPPETEER_DOWNLOAD_HOST
-
PUPPETEER_SKIP_DOWNLOAD（跳过下载）
例如将下载源切换到国内镜像，可以显著提升成功率。
同时在 npm install 前设置：
-
npm config set puppeteer_download_host https://npmmirror.com/mirrors
这种方式适用于 CI 环境或公司内网服务器。
2. 代理网络访问
在海外依赖环境无法访问时，可以通过 HTTP/HTTPS 代理：
-
export HTTP_PROXY
-
export HTTPS_PROXY
在 Docker 构建过程中尤其有效，否则 Chromium 会因为超时直接失败。
二、跳过 Chromium 自动下载的方案
在生产环境中，很多团队并不希望 Puppeteer 自动下载浏览器，而是使用系统已有 Chromium。
可以通过以下方式跳过：
-
设置 PUPPETEER_SKIP_DOWNLOAD=true
-
手动安装 chromium-browser 或 google-chrome-stable
-
在 launch 时指定 executablePath
例如：
JavaScriptpuppeteer.launch({
executablePath: '/usr/bin/google-chrome-stable'
})
这种方式可以大幅减少 CI 构建时间，并避免重复下载带来的不稳定因素。
三、Docker 环境中的典型问题
Docker 是 Chromium 下载失败的高发环境之一，主要原因包括：
-
基础镜像缺少依赖库
-
网络访问受限
-
缓存目录权限问题
解决思路如下：
1. 安装依赖库
Chromium 依赖 glib、nss、fonts 等系统库，否则即使下载成功也无法启动。
2. 使用官方 Puppeteer Docker 镜像
官方镜像已经预装 Chromium 及依赖，是最稳定的方案之一。
3. 设置缓存目录
通过 PUPPETEER_CACHE_DIR 指定缓存路径，避免无权限写入导致下载失败。
四、版本不匹配导致的隐性错误
有时候 Chromium 实际下载成功，但仍然报错 revision not downloaded，这通常是版本映射问题。
原因包括：
-
Puppeteer 版本升级但缓存未更新
-
node_modules 残留旧版本
-
lockfile 锁定旧依赖
解决方式：
-
删除 node_modules 和 package-lock.json
-
重新安装 puppeteer
-
清理 ~/.cache/puppeteer 目录
保持 Puppeteer 与 Chromium 版本一致非常关键，否则即使启动成功，也可能出现页面崩溃或渲染异常。
五、离线安装 Chromium 的稳定方案
在企业级部署中，最稳定的方式是完全离线管理 Chromium：
-
预先下载 Chromium 压缩包
-
解压到固定路径
-
通过 executablePath 指向本地浏览器
-
禁用自动下载机制
这种方式虽然增加部署成本，但可以彻底规避网络依赖问题，适用于金融、数据平台等高稳定性场景。
六、CI/CD 环境优化策略
在 GitHub Actions、GitLab CI 中，推荐如下配置思路：
-
使用缓存机制保存 Chromium
-
设置 PUPPETEER_CACHE_DIR 到 workspace
-
使用镜像源加速下载
-
分离 install 与 build 阶段
通过缓存可以避免每次 pipeline 都重新下载 Chromium，大幅提升构建效率。
七、长期稳定性的工程实践
要彻底解决 Puppeteer Chromium 下载问题，需要从架构层面优化：
-
固定 Puppeteer 版本
-
固定 Chromium 版本
-
使用统一镜像源
-
在 Docker 中预装浏览器
-
引入构建缓存机制
稳定的自动化系统，不依赖每次动态下载浏览器，而是依赖可控的运行环境，这才是生产级 Puppeteer 的正确使用方式。
当 Chromium 下载不再是运行时问题，整个自动化流程的可靠性会显著提升，也能避免大量隐性故障。
