Puppeteer在macOS Sequoia系统中运行报错"Error: socket hang up"的解决方案

问题背景

最近有开发者反馈，在将macOS系统从Sonoma升级到Sequoia后，原本正常运行的Puppeteer脚本突然出现"Error: socket hang up"错误。这个问题主要出现在使用Puppeteer 23.5.1版本和Node.js 22.12.0环境下，当尝试以非无头模式(headless: false)启动浏览器时。

错误现象

当执行包含以下代码的脚本时：

const browser = await puppeteer.launch({headless: false});

系统会抛出如下错误：

Error: socket hang up
    at Socket.socketOnEnd (node:_http_client:536:25)
    at Socket.emit (node:events:536:35)
    at endReadableNT (node:internal/streams/readable:1698:12)
    at process.processTicksAndRejections (node:internal/process/task_queues:90:21) {
  code: 'ECONNRESET'
}

问题分析

这个错误表明Puppeteer无法与浏览器实例建立稳定的WebSocket连接。在macOS系统升级后，可能出现以下情况：

1. 系统权限变更：Sequoia可能引入了新的安全限制，影响了Puppeteer与浏览器的通信
2. 默认浏览器路径变化：系统升级可能导致Puppeteer无法自动定位到正确的浏览器可执行文件
3. 网络连接限制：新系统可能对本地回环(127.0.0.1)连接有更严格的限制

解决方案

经过验证，可以通过显式指定Chrome浏览器的可执行路径来解决此问题：

const browser = await puppeteer.launch({
  headless: false,
  executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
});

深入理解

这个解决方案有效的根本原因在于：

1. 路径明确性：直接指定可执行路径避免了Puppeteer在系统升级后可能出现的浏览器定位问题
2. 权限一致性：使用完整路径可以确保系统正确识别和授权该应用程序的网络连接
3. 版本匹配：确保使用的是开发者预期的Chrome版本，避免自动选择可能不兼容的浏览器版本

最佳实践建议

1. 在生产环境中，始终建议显式指定浏览器路径
2. 考虑使用try-catch块捕获启动异常，并提供有意义的错误提示
3. 对于跨平台应用，可以根据不同操作系统动态构建executablePath
4. 定期检查并更新Puppeteer版本，确保与新系统版本的兼容性

总结

macOS系统升级有时会带来一些意料之外的兼容性问题。通过显式指定浏览器路径这种简单而有效的方法，开发者可以快速解决Puppeteer在新系统中的连接问题。这也提醒我们，在关键自动化脚本中，对依赖项进行明确配置的重要性。