WhatsApp Web JS客户端连接异常与Linux登录设备标识显示错误求助

一、设备显示为“Google Chrome (Mac OS)”的修复 #

问题根源 #

WhatsApp Web JS 依赖的 puppeteer 组件默认会使用预设的用户代理（UA）字符串，或自动下载适配当前系统的 Chromium，但 Linux 环境下可能因配置缺失，导致 UA 中的系统标识被错误识别为 Mac OS。

解决步骤 #

• 手动指定 Linux 专属 UA：初始化客户端时，通过 puppeteer 配置强制设置包含 Linux 信息的用户代理：

  const { Client } = require('whatsapp-web.js');
  const client = new Client({
      puppeteer: {
          args: ['--no-sandbox'],
          userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36'
      }
  });
  

• 绑定本地 Chromium 可执行文件：确保 Linux 系统安装了原生 Chromium（通过 apt install chromium-browser 或对应包管理器安装），然后在配置中指定其路径：

  puppeteer: {
      executablePath: '/usr/bin/chromium-browser',
      args: ['--no-sandbox', '--disable-setuid-sandbox'],
      userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36'
  }
  

二、“Client not connected properly” 问题排查 #

常见修复方案 #

• 关闭 puppeteer 沙箱：Linux 环境下非 root 用户运行时，必须添加 --no-sandbox 和 --disable-setuid-sandbox 参数到 puppeteer 的 args 数组中，避免权限限制导致启动失败。
• 检查会话文件权限：如果启用了会话持久化（配置了 sessionPath），确保 Node.js 进程对该文件拥有读写权限，否则会因会话加载失败导致连接中断。
• 验证网络连通性：执行 curl -I https://web.whatsapp.com 测试服务器能否正常访问 WhatsApp Web 官方域名，排除防火墙、代理拦截的可能。
• 捕获错误日志定位问题：在代码中添加错误监听，获取具体失败原因：

  client.on('auth_failure', msg => {
      console.error('认证失败:', msg);
  });
  client.on('disconnected', reason => {
      console.error('客户端断开:', reason);
  });
  

• 更新依赖版本：执行 npm update whatsapp-web.js puppeteer，确保依赖为最新稳定版，避免旧版本兼容性问题。

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