如何解决ERROR: Failed to download Chromium r686378! Set “PUPPETEER_SKIP_CHROMIUM_DOWNLOAD” env variable to skip download.

在AI基础设施和模型部署的场景中，我们经常需要使用像Puppeteer这样的无头浏览器库来处理数据预处理、生成报告或进行爬虫任务。然而，当我们在Docker容器或CI/CD流水线中运行npm install时，常常会遇到一个令人沮丧的错误：ERROR: Failed to download Chromium r686378! Set “PUPPETEER_SKIP_CHROMIUM_DOWNLOAD” env variable to skip download.

这个问题通常是由于以下原因导致的：
1. 网络限制：容器或CI环境无法访问Google的下载服务器（下载Chromium二进制文件）。
2. 镜像大小：Chromium二进制文件体积庞大（通常超过170MB），导致构建时间过长或存储空间不足。
3. 系统依赖缺失：即使下载成功，在最小化的Linux发行版（如Alpine或Slim Node镜像）中，Chromium所需的底层运行库可能缺失。

解决这个问题的核心思路是：要么确保下载能成功，要么彻底跳过Puppeteer的自动下载机制，并手动提供一个运行环境。

策略一：跳过自动下载并优化安装（推荐）

既然错误信息建议跳过下载，这是解决网络限制问题的最快方法。但请注意，如果跳过了下载，您的代码运行时就必须指向一个可用的Chromium或Chrome浏览器路径。

1. 设置环境变量

在执行npm install之前，设置环境变量来跳过Chromium的下载：

1
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install

2. 使用puppeteer-core代替全量包（可选优化）

如果您的目标环境是容器或服务器，并且您自己管理浏览器安装，建议使用更轻量的puppeteer-core包。它只包含API，不包含Chromium二进制文件。

1
npm install puppeteer-core

策略二：为Docker部署构建优化的运行环境

对于生产环境部署，最佳实践是使用Docker来封装应用程序和所有依赖。下面的Dockerfile展示了如何在基于Debian的Node镜像中，跳过Puppeteer的下载，并手动安装运行Chromium所需的系统级依赖。

关键点： 即使跳过了Puppeteer的下载，Chromium的运行时依赖（如字体、图形库等）仍然需要手动安装。

示例Dockerfile

我们使用node:18-slim作为基础镜像，它比标准的Node镜像更小，但需要我们安装额外的运行库。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
# 阶段 1: 安装依赖和系统运行时库

FROM node:18-slim AS base



# 设置环境变量，确保Puppeteer在npm install时不下载庞大的Chromium

ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true



# 安装运行Chromium所需的所有核心系统依赖

# 这些依赖确保headless模式可以正常工作

RUN apt-get update \

    && apt-get install -y --no-install-recommends \

        ca-certificates \

        fonts-liberation \

        libappindicator3-1 \

        libasound2 \

        libatk-bridge2.0-0 \

        libnspr4 \

        libnss3 \

        libx11-xcb1 \

        libxcomposite1 \

        libxdamage1 \

        libxfixes3 \

        libxrandr2 \

        libxrender1 \

        libxtst6 \

        wget \

    && rm -rf /var/lib/apt/lists/*



WORKDIR /app

COPY package.json package-lock.json ./



# 执行npm install，此时由于环境变量，将跳过Chromium下载

RUN npm install



# 将一个已知的Chrome/Chromium安装到容器中

# 警告: 生产环境推荐使用官方提供的Chrome Docker镜像或更可靠的源

# 假设我们使用官方Chromium路径（或自己手动安装）

# 如果依赖于系统默认安装的Chrome，则不需要这一步，但需要确保Chrome/Chromium已通过 apt-get 安装



# 假设系统安装了默认的Chromium

RUN apt-get update && apt-get install -y chromium



# 阶段 2: 最终运行镜像 (可选，用于减小体积)

FROM base



# 确保Puppeteer知道Chromium的路径

ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium



# 运行应用

CMD ["node", "your_script.js"]

3. 在代码中指定Chromium路径

如果您在Dockerfile中手动安装了Chromium，您必须确保Puppeteer知道在哪里找到它。这可以通过设置PUPPETEER_EXECUTABLE_PATH环境变量完成，如上所示，或者在您的Node.js代码中指定executablePath：

1
2
3
4
5
6
7
8
9
10
11
12
13
const puppeteer = require('puppeteer-core'); // 使用 core 包



async function runBrowser() {

  const browser = await puppeteer.launch({

    // 这里的路径必须指向容器内实际安装的 Chromium/Chrome 可执行文件

    executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || '/usr/bin/chromium',

    args: ['--no-sandbox', '--disable-setuid-sandbox']

  });

  // ... 您的业务逻辑

  await browser.close();

}



runBrowser();

通过设置PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true并配合一个包含系统依赖和手动安装的Chromium（或Chrome）的Docker镜像，您可以高效且稳定地在任何部署环境中运行Puppeteer任务。