Puppeteer launch无明确原因失效 同代码在原生Node.js正常Nest.js中报错

核心原因排查 #

Nest.js 项目和原生 Node.js 项目的运行环境存在差异，大部分启动失败都来自路径、执行上下文、打包配置三类问题，可按照以下步骤逐一排查：

1. 先打印完整错误堆栈定位根因 #

给 puppeteer.launch 包裹 try/catch 输出完整错误信息，绝大多数无明确报错的情况都是没有捕获到内部抛出的异常：

try {
  const browser = await puppeteer.launch({
    // 你的原有配置
  })
} catch (e) {
  // 输出完整堆栈后可直接定位是找不到Chrome二进制、权限不足还是内存不足等问题
  console.error('Puppeteer 启动完整错误：', e)
}

2. 排查 Chrome 二进制路径问题 #

Nest.js 会将 TS 代码编译到 dist 目录下运行，运行时的相对路径是基于 dist 内的执行文件，而非源码目录，原生 Node.js 项目通常直接运行源码目录下的文件，二者路径上下文不同会导致 Puppeteer 找不到内置的 Chrome 二进制。
临时验证方案：手动指定本地 Chrome 的绝对路径到配置中，确认是否是路径问题：

const browser = await puppeteer.launch({
  headless: 'new', // 建议用新版headless模式，兼容性更好
  // 替换为你设备对应的Chrome安装路径
  // Mac 示例：'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
  // Windows 示例：'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
  // Linux 示例：'/usr/bin/google-chrome-stable'
  executablePath: '你的Chrome绝对安装路径',
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage', // 新增该参数解决共享内存不足的常见问题
    '--no-first-run',
    '--no-default-browser-check'
  ]
})

3. 排查异步执行逻辑问题 #

确认你在 Nest.js 中调用 puppeteer.launch 的位置是否正确加了 await，如果是在模块生命周期钩子（如 onModuleInit）、接口请求处理方法中调用，未加 await 会导致异步逻辑未执行完成就被销毁，表现为无响应无报错。

4. 排查打包配置问题 #

如果你的 Nest.js 项目开启了 Webpack 打包，需要将 puppeteer 设为外置依赖不参与打包，否则打包过程会丢失 Puppeteer 关联的二进制文件路径配置，在 nest-cli.json 中添加以下配置即可：

{
  "compilerOptions": {
    "deleteOutDir": true,
    "webpack": true,
    "assets": ["**/*.pem"],
    "plugins": []
  },
  "webpackConfigPath": "webpack.config.js"
}

对应 webpack.config.js 配置：

module.exports = {
  externals: {
    puppeteer: 'commonjs puppeteer'
  }
}

5. 核对依赖版本 #

确认 Nest.js 项目和原生 Node.js 项目安装的 Puppeteer 版本完全一致，跨版本的 Puppeteer 对 Chrome 版本的要求不同，也会出现兼容问题。

内容的提问来源于stack exchange，提问作者Stefan Stanković