npm 安装 Puppeteer 缓慢的解决方法

装 puppeteer 卡住，卡的通常不是 npm 包本身，而是它 install 脚本里那一步下载 Chromium 的动作。那是个上百 MB 的浏览器二进制，默认从 Google 的存储地址拉，国内基本下不动，表现就是安装进度长时间停在原地，最后以超时或者校验失败告终。

解决思路是把这个下载地址换成国内镜像。注意这不是 npm 的 registry 配置，registry 只管 npm 包；Chromium 的下载地址是 puppeteer 自己读的一个独立配置项，两者必须分别设置。

puppeteer 安装缓慢处理

先写入下载源配置，再执行安装。npm config set 会把这项存进 ~/.npmrc，所以只需要设一次，后续在其它项目装 puppeteer 也同样生效。

npm config set puppeteer_download_host=https://npm.taobao.org/mirrors
npm install puppeteer

注意事项

• 配置项名字随 puppeteer 版本变过：老版本认 puppeteer_download_host，新版本（v20 之后）改用 PUPPETEER_DOWNLOAD_BASE_URL，而且下载的东西也从 Chromium 换成了 Chrome for Testing。装不动时先看一眼自己装的是哪个大版本，配错了名字等于没配。
• 淘宝镜像域名同样建议改用 https://registry.npmmirror.com/-/binary/chromium-browser-snapshots（旧的 npm.taobao.org/mirrors 只靠重定向维持）。
• 如果机器上已经有可用的 Chrome，也可以设 PUPPETEER_SKIP_DOWNLOAD=true 完全跳过下载，运行时用 executablePath 指向本地浏览器。代价是要自己保证浏览器版本和 puppeteer 的协议兼容。
• CI 镜像里跑 headless Chrome 常缺一堆系统库（libnss3、libatk 之类），那是运行时报错，和下载慢是两个问题，别混在一起排查。