Node.js 与 Puppeteer 部署故障排查手册
日期： 2026-03-30
环境： Linux Server (Ubuntu/Debian), Node.js, Puppeteer
1. 报错：Could not find Chrome
在执行脚本或启动应用时，提示找不到 Chrome 浏览器，或者提示 npm 找不到 package.json。
npm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '/root/package.json'
...
Could not find Chrome (ver. 146.0.7680.153). This can occur if either... your cache path is incorrectly configured
...
Could not find Chrome (ver. 146.0.7680.153). This can occur if either... your cache path is incorrectly configured
💡 原因分析
- 路径错误： 在终端直接运行 `npm` 命令时，当前目录位于 `/root`，而项目代码在别处，导致找不到 `package.json`。
- 浏览器缺失： Puppeteer 依赖的 Chrome 二进制文件下载失败或被意外删除，导致缓存目录中找不到对应的浏览器版本。
🛠️ 解决方案
步骤 1：进入正确的项目目录
不要直接在 `/root` 下运行命令，必须先 `cd` 到你的项目文件夹。
cd /www/wwwroot/你的项目名 ls # 确认能看到 package.json
步骤 2：放弃 Puppeteer 自带的 Chrome，改用系统 Chromium（推荐）
为了避免版本不匹配和下载失败，最稳妥的方法是安装系统级的浏览器。
sudo apt-get update sudo apt-get install -y chromium
2. 报错：chrome_crashpad_handler: --database is required
这是最顽固的错误，发生在浏览器启动瞬间，导致进程直接崩溃。
Failed to launch the browser process: Code: null
stderr:
chrome_crashpad_handler: --database is required
Try 'chrome_crashpad_handler --help' for more information.
[234714:234714:0330/060219.431575:ERROR:third_party/crashpad/crashpad/util/linux/socket.cc:120] recvmsg: Connection reset by peer (104)
stderr:
chrome_crashpad_handler: --database is required
Try 'chrome_crashpad_handler --help' for more information.
[234714:234714:0330/060219.431575:ERROR:third_party/crashpad/crashpad/util/linux/socket.cc:120] recvmsg: Connection reset by peer (104)
💡 原因分析
这个错误与“无法访问网站”无关，而是 Chrome 浏览器内部的崩溃报告组件（Crashpad）在启动时缺少必要的参数或环境支持。这通常发生在使用 Puppeteer 自带的精简版 Chrome 时。
🛠️ 解决方案
必须同时满足两个条件：使用系统 Chromium + 禁用 Crashpad。
步骤 1：确认系统 Chromium 路径
which chromium # 输出通常为: /usr/bin/chromium
步骤 2：修改代码配置
在 `puppeteer.launch` 中强制指定 `executablePath` 并添加 `--disable-crashpad` 参数。
const browser = await puppeteer.launch({
// 【关键】指定系统 Chromium 路径，不再使用 Puppeteer 自带的 Chrome
executablePath: '/usr/bin/chromium',
headless: 'new',
args: [
'--no-sandbox', // 必需：允许 root 运行
'--disable-setuid-sandbox', // 必需：解决 sandbox 权限问题
'--disable-crashpad', // 【核心】禁用崩溃报告，解决 --database 错误
'--disable-dev-shm-usage' // 推荐：防止 /dev/shm 空间不足
]
});
步骤 3：清理缓存（可选但推荐）
rm -rf ~/.cache/puppeteer
3. 最终正确配置总结
为了确保你的服务稳定运行，请确保你的服务器环境和代码符合以下标准：
✅ 环境准备 (终端执行)
# 1. 安装依赖库和系统浏览器 sudo apt-get update sudo apt-get install -y chromium ca-certificates fonts-liberation \ libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 \ libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 \ 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 \ xdg-utils
✅ 代码配置 (Node.js)
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
// 强制使用系统浏览器
executablePath: '/usr/bin/chromium',
headless: 'new',
args: [
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-crashpad', // 解决 crashpad 报错
'--disable-dev-shm-usage'
]
});
const page = await browser.newPage();
await page.goto('https://example.com');
// ... 其他逻辑
await browser.close();
})();