Puppeteer常见问题排查与解决方案指南

最新推荐文章于 2025-06-10 09:01:05 发布

苗韵列Ivan

最新推荐文章于 2025-06-10 09:01:05 发布

阅读量222

点赞数 4

本文链接：https://blog.csdn.net/gitblog_01059/article/details/148323111

版权

Puppeteer常见问题排查与解决方案指南

puppeteer Puppeteer是Google开发的自动化操控Chrome浏览器的API，通过它可以实现网页抓取、自动化测试、生成预渲染内容等功能，尤其在Web应用的端到端测试和爬虫领域有广泛应用。项目地址: https://gitcode.com/gh_mirrors/pu/puppeteer

前言

Puppeteer作为一款强大的Node.js库，为开发者提供了控制Chrome/Chromium浏览器的高级API。但在实际使用过程中，开发者可能会遇到各种环境配置和运行问题。本文将系统梳理Puppeteer使用中的常见问题及其解决方案，帮助开发者快速定位和解决问题。

模块加载问题

找不到内部模块错误

问题现象：出现Cannot find module 'puppeteer-core/internal/...'错误。

原因分析：

Node.js版本低于14
使用了自定义模块解析器（如jest-resolve）

解决方案：

升级Node.js到14或更高版本
如果是自定义解析器问题，升级相关依赖（如jest及其解析器）

浏览器下载与缓存问题

本地找不到浏览器

问题现象：Could not find expected browser locally错误。

背景说明：从v19.0.0开始，Puppeteer默认将浏览器下载到~/.cache/puppeteer目录。

解决方案：

环境变量方式：

PUPPETEER_CACHE_DIR=$(pwd) npm install puppeteer
PUPPETEER_CACHE_DIR=$(pwd) node <脚本路径>

配置文件方式：在项目根目录创建.puppeteerrc.cjs文件：
```
const {join} = require('path');

module.exports = {
  cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
};
```
然后重新安装Puppeteer使配置生效。

HTTP导航问题

ERR_BLOCKED_BY_CLIENT错误

问题现象：导航到HTTP网址时出现net::ERR_BLOCKED_BY_CLIENT错误。

原因：Chrome的HttpsFirstBalancedModeAutoEnable功能会阻止HTTP网站访问。

解决方案：

通过启动参数禁用该功能：

const browser = await puppeteer.launch({
  args: ['--disable-features=HttpsFirstBalancedModeAutoEnable'],
});

或者点击警告页面上的继续按钮（可通过Puppeteer自动化）

Windows系统问题

Chrome无法启动

问题现象：Chrome因策略限制无法启动。

原因：某些Chrome策略强制要求启用扩展，而Puppeteer默认禁用扩展。

解决方案：

const browser = await puppeteer.launch({
  enableExtensions: true,
});

沙盒错误

问题现象：出现sandbox_win.cc相关错误。

解决方案：

自动方案（Puppeteer v22.14.0+）： Puppeteer会自动配置权限。

手动方案：

icacls "%USERPROFILE%/.cache/puppeteer/chrome" /grant *S-1-15-2-1:(OI)(CI)(RX)

Linux系统问题

依赖缺失

通用检查方法：

ldd chrome | grep not

Debian/Ubuntu依赖：

sudo apt install ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 \
libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 \
libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 \
libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 \
libxss1 libxtst6 lsb-release wget xdg-utils

CentOS依赖：

sudo yum install alsa-lib.x86_64 atk.x86_64 cups-libs.x86_64 gtk3.x86_64 \
ipa-gothic-fonts libXcomposite.x86_64 libXcursor.x86_64 libXdamage.x86_64 \
libXext.x86_64 libXi.x86_64 libXrandr.x86_64 libXScrnSaver.x86_64 \
libXtst.x86_64 pango.x86_64 xorg-x11-fonts-100dpi xorg-x11-fonts-75dpi \
xorg-x11-fonts-cyrillic xorg-x11-fonts-misc xorg-x11-fonts-Type1 \
xorg-x11-utils

sudo yum update nss -y

ARM64架构问题

注意：Chrome目前不提供Linux ARM64二进制文件，只有Mac ARM64版本。

沙盒配置

禁用沙盒（不推荐）

const browser = await puppeteer.launch({
  args: ['--no-sandbox'],
});

AppArmor问题（Ubuntu 23.10+）

问题现象：No usable sandbox!错误。

解决方案：参考Chrome官方文档解决AppArmor限制。

CI环境配置

Travis CI配置示例

language: node_js
node_js: node
services: xvfb
script:
  - npm test

CircleCI配置要点

使用Node.js镜像
安装必要依赖（如libXtst6）
对于Jest用户，设置合理的maxWorkers

Docker配置

基础Dockerfile示例

FROM node:14-slim

RUN apt-get update && apt-get install -y wget gnupg \
    && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \
    && apt-get update \
    && apt-get install -y google-chrome-stable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf libxss1 \
      --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

RUN npm init -y && \
    npm i puppeteer \
    && groupadd -r pptruser && useradd -r -g pptruser -G audio,video pptruser \
    && mkdir -p /home/pptruser/Downloads \
    && chown -R pptruser:pptruser /home/pptruser \
    && chown -R pptruser:pptruser /node_modules

USER pptruser

Alpine Linux特殊说明

Chrome官方不支持Alpine，需要手动安装兼容版本：

FROM alpine

RUN apk add --no-cache \
      chromium \
      nss \
      freetype \
      harfbuzz \
      ca-certificates \
      ttf-freefont \
      nodejs \
      yarn

ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

RUN yarn add puppeteer@13.5.0  # 与Chromium 100兼容的版本

RUN addgroup -S pptruser && adduser -S -G pptruser pptruser \
    && mkdir -p /home/pptruser/Downloads /app \
    && chown -R pptruser:pptruser /home/pptruser \
    && chown -R pptruser:pptruser /app

USER pptruser