使用node-html-to-image报错Unable to get browser page如何解决

故障表现 #

• 运行环境：Node.js
• 故障触发场景：昨日可正常运行的node-html-to-image相关代码，在未做任何代码修改的情况下今日全部运行失败
• 复现验证：新建空白测试项目，仅运行官方README提供的默认示例代码，仍触发完全相同的错误
• 已尝试操作：在Promise调用链末尾添加.catch()捕获异常，问题未解决，无后续排查思路

报错信息 #

(node:67808) UnhandledPromiseRejectionWarning: Error: Unable to get browser page
    at Worker.<anonymous> (G:\ONEDRIVE\{DIRECTORY}\School\html-to-image-test\node_modules\puppeteer-cluster\dist\Worker.js:41:31)
    at Generator.next (<anonymous>)
    at fulfilled (G:\ONEDRIVE\{DIRECTORY}\School\html-to-image-test\node_modules\puppeteer-cluster\dist\Worker.js:5:58)
    at processTicksAndRejections (internal/process/task_queues.js:93:5)
(node:67808) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:67808) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

最小复现代码 #

const nodeHtmlToImage = require('node-html-to-image')

nodeHtmlToImage({
  output: './image.png',
  html: '<html><body>Hello world!</body></html>'
})
  .then(() => console.log('The image was created successfully!'))

故障原因与解决方法 #

这个报错的核心原因是node-html-to-image依赖的puppeteer-cluster无法正常拉起浏览器实例，和业务代码、示例代码本身无关，无修改突发故障通常是底层浏览器运行环境异常导致，按以下顺序排查即可：

• 首先清理依赖重新安装：删除项目下的node_modules目录、对应包管理器的锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），重新执行依赖安装命令，强制重新拉取完整的puppeteer和配套Chromium文件，解决缓存文件被误删、损坏的问题。
• 如果重装依赖无效，直接指定本地已安装的正式版Chrome/Edge作为puppeteer的启动浏览器，跳过自带Chromium的加载，修改调用代码传入启动参数即可：

  const nodeHtmlToImage = require('node-html-to-image')
  
  nodeHtmlToImage({
    output: './image.png',
    html: '<html><body>Hello world!</body></html>',
    puppeteerArgs: {
      // 替换为本地浏览器的实际安装路径
      // Windows Chrome默认路径: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
      // Windows Edge默认路径: 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe'
      // Mac Chrome默认路径: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
      // Linux Chrome默认路径: '/usr/bin/google-chrome-stable'
      executablePath: '替换为你本地的浏览器路径',
      args: ['--no-sandbox', '--disable-setuid-sandbox']
    }
  })
  .then(() => console.log('The image was created successfully!'))
  .catch(err => console.error('生成失败:', err))
  

• 检查系统安全软件、防火墙的拦截记录，把Node.js进程、puppeteer的缓存目录加入白名单，避免浏览器子进程拉起时被权限拦截。
• Windows环境如果近期安装过系统安全补丁，部分补丁会默认拦截未签名的Chromium进程，使用上面指定本地正式版浏览器的方法即可绕过该限制。

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