树莓派上Chromium卡在about:blank，Puppeteer运行异常求助

1. 确认Chromium的准确路径 #

树莓派上的Chromium执行路径可能不是简单的chromium-browser，先通过命令定位真实路径：

which chromium-browser
# 或尝试
which chromium

将得到的完整路径（比如/usr/bin/chromium-browser）替换到代码的executablePath配置项中。

2. 添加树莓派专属启动参数 #

无桌面环境的树莓派需要特定参数才能让Chromium被Puppeteer正常驱动，修改启动配置：

const browser = await puppeteer.launch({
  executablePath: '/usr/bin/chromium-browser', // 替换为你找到的真实路径
  headless: 'new', // 新版无头模式兼容性更好
  args: [
    '--no-sandbox', // 树莓派权限限制下必须关闭沙箱
    '--disable-dev-shm-usage', // 避免/dev/shm空间不足导致卡死
    '--disable-gpu', // 禁用GPU加速，适配树莓派硬件
    '--disable-setuid-sandbox',
    '--single-process', // 单进程模式减少资源占用
    '--no-zygote'
  ]
});

3. 匹配Puppeteer与Chromium版本 #

Puppeteer对Chrome/Chromium版本有严格依赖，报错里提到的113.0.5672.63是Puppeteer期望的版本，可通过两种方式对齐：

• 安装对应版本的Chromium：

  sudo apt install chromium-browser=113.0.5672.63-rpt1
  

  若找不到该版本，先更新Raspberry Pi官方源再重试。
• 安装适配本地Chromium的Puppeteer：
  先查看本地Chromium版本：

  chromium-browser --version
  

  再安装对应版本的Puppeteer，比如本地Chromium是120.x，就执行：

  npm install puppeteer@21
  

4. 补全依赖与修复权限 #

• 确保当前用户有Chromium执行权限：

  sudo chmod +x /usr/bin/chromium-browser
  

• 安装Chromium缺失的依赖库：

  sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm-dev libxkbcommon-dev libgbm-dev libasound2 libatspi2.0-0 libxshmfence1
  

5. 手动指定缓存路径 #

若提示缓存路径错误，可自定义缓存目录并授权：

const browser = await puppeteer.launch({
  executablePath: '/usr/bin/chromium-browser',
  userDataDir: '/home/pi/puppeteer-cache', // 自定义缓存路径
  args: [...其他参数]
});

提前创建目录并设置权限：

mkdir -p /home/pi/puppeteer-cache
chown pi:pi /home/pi/puppeteer-cache

内容的提问来源于stack exchange，提问作者Simmelari