Puppeteer 下载慢？这些实操方案亲测有效

作为一名全站开发人员，在日常项目开发中，Puppeteer 是我常用的自动化测试和网页爬取工具。但相信很多同行都遇到过同一个问题——Puppeteer 安装时下载速度异常缓慢，甚至频繁出现下载失败的情况，严重影响开发进度。经过多次踩坑和实践，我整理了自己平时解决该问题的几种常用方法，全程实操可落地，分享给有需要的小伙伴。

首先要明确的是，Puppeteer 下载慢的核心原因的在于，它在安装过程中会默认从谷歌官方服务器下载 Chromium 浏览器，而国内网络环境访问谷歌服务器存在天然壁垒，导致下载速度卡顿、超时，这并不是工具本身的问题，也不是我们的网络故障，只需针对性调整下载来源或使用方式，就能轻松解决。

一、国内镜像源配置（最常用、最高效）

这是我平时最常使用的方法，无需复杂操作，只需设置环境变量，指定国内的 Chromium 镜像源，就能让 Puppeteer 从国内服务器下载所需文件，下载速度会有质的提升，几乎不会出现超时失败的情况。 不同操作系统的设置方式略有差异，以下是我平时实操过的具体步骤，亲测全部有效：

1. Windows 系统（cmd 命令行）

如果使用的是普通的 cmd 命令行，只需先设置临时环境变量，再执行安装命令即可，临时环境变量仅在当前窗口有效，适合偶尔安装的场景：

# 设置临时环境变量（仅当前窗口有效）
set PUPPETEER_DOWNLOAD_HOST=https://npmmirror.com/mirrors 
# 然后安装 puppeteer
npm install puppeteer

2. Windows PowerShell

如果习惯使用 PowerShell 进行命令操作，环境变量的设置语法略有不同，具体如下：

# 设置临时环境变量
$env:PUPPETEER_DOWNLOAD_HOST="https://npmmirror.com/mirrors"
# 安装 puppeteer
npm install puppeteer

3. Mac/Linux 系统（终端）

Mac 和 Linux 系统的操作更为简洁，可以直接将环境变量设置和安装命令合并执行，一步到位：

# 设置临时环境变量并安装
PUPPETEER_DOWNLOAD_HOST=https://npmmirror.com/mirrors npm install puppeteer

4. 永久生效配置（可选）

如果经常需要安装 Puppeteer，不想每次都重复设置环境变量，可以将镜像源配置到 npm 全局设置中，之后每次安装直接执行 npm install puppeteer 即可，无需再额外设置：

# 配置 npm 镜像
npm config set puppeteer_download_host https://npmmirror.com/mirrors 
# 之后直接安装即可
npm install puppeteer

二、手动下载 Chromium 并指定路径

如果遇到镜像源配置后仍有下载问题，或者网络环境特殊，无法通过镜像源下载，手动下载 Chromium 并指定路径也是一个可靠的方案。这种方式虽然步骤稍多，但胜在稳定，适合各种复杂网络环境。 具体操作步骤如下：

1. 手动下载 Chromium

访问国内镜像地址： https://npmmirror.com/mirrors/chromium-browser-snapshots/ ，该地址收录了各个版本、各个系统的 Chromium 安装包，下载时只需根据自己的操作系统（Win/Mac/Linux）和电脑架构（x64/arm64），选择对应的版本下载即可。下载完成后，解压到本地一个固定的路径，比如 Windows 下可以放在 D:\chromium，Mac/Linux 下可以放在 /usr/local/chromium，方便后续调用。

2. 在代码中指定 Chromium 路径

下载并解压完成后，需要在代码中明确指定本地 Chromium 的路径，让 Puppeteer 不再自动下载，直接使用本地已有的浏览器文件。以下是具体的代码示例，可根据自己的系统路径进行修改：

const puppeteer = require('puppeteer');

(async () => {
  // 指定本地 Chromium 的路径
  const browser = await puppeteer.launch({
    executablePath: 'D:\\chromium\\chrome.exe', // Windows 路径
    // executablePath: '/usr/local/chromium/chrome', // Mac/Linux 路径
    headless: true // 无头模式，可选
  });

  const page = await browser.newPage();
  await page.goto('https://www.baidu.com');
  console.log(await page.title());
  
  await browser.close();
})();

三、使用 puppeteer-core（轻量版，复用本地浏览器）

还有一种情况，就是我们的电脑上已经安装了 Chrome 或 Edge 浏览器，此时完全不需要再下载 Chromium，只需使用 puppeteer-core（Puppeteer 的轻量版），手动指定本地已安装的浏览器路径即可，既节省空间，又能避免下载环节。 具体操作步骤如下：

1. 安装 puppeteer-core

puppeteer-core 不包含自动下载 Chromium 的功能，体积更小，安装速度更快，直接执行以下命令即可完成安装：

npm install puppeteer-core

2. 代码中指定本地浏览器路径

安装完成后，在代码中指定本地已安装的 Chrome 或 Edge 浏览器路径，即可正常使用 Puppeteer 的所有功能。以下是不同系统的路径示例，可根据自己的实际情况修改：

const puppeteer = require('puppeteer-core');

(async () => {
  // Windows 下的 Edge 浏览器路径示例
  const browser = await puppeteer.launch({
    executablePath: 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
    // Mac 下 Chrome 路径：/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
    headless: true
  });

  const page = await browser.newPage();
  await page.goto('https://www.baidu.com');
  console.log(await page.title());
  
  await browser.close();
})();

最后补充

以上三种方法，是我在长期开发中总结出来的、亲测有效的解决方案。其实 Puppeteer 下载慢的问题，本质上就是“下载来源”的问题，要么换国内镜像源，要么跳过自动下载、手动指定浏览器路径，无论哪种方法，都能有效解决卡顿、超时的问题。

平时开发中，我最常用的是第一种方法，简单高效；如果遇到特殊网络环境，会选择第二种或第三种方法，根据实际场景灵活调整即可。希望这些实操经验，能帮助到正在被 Puppeteer 下载慢困扰的同行们，少踩坑、提高开发效率。