WhatsApp-web.js ready事件未触发问题求助

扫码完成后ready事件始终未触发，可从以下几个方面排查解决：

1. 检查会话缓存权限与配置 #

whatsapp-web.js默认会在项目根目录的./.wwebjs_cache存储登录会话数据，若该目录无读写权限，扫码后的会话无法持久化，会导致客户端始终无法进入就绪状态。

• 可手动指定具备读写权限的缓存目录：

  const client = new Client({
    puppeteer: {
      userDataDir: './custom_session_cache' // 自定义缓存路径
    }
  });
  

2. 添加错误事件监听定位问题 #

通过监听auth_failure、disconnected、error事件，能直接捕获认证失败、连接断开等底层问题：

// 新增错误监听逻辑
client.on('auth_failure', (msg) => {
  console.error('认证失败:', msg);
});

client.on('disconnected', (reason) => {
  console.log('客户端断开:', reason);
});

client.on('error', (err) => {
  console.error('客户端错误:', err);
});

3. 启用有头浏览器调试 #

无头浏览器可能存在加载异常，临时开启有头模式，直观查看WhatsApp Web页面的实际状态（比如是否有两步验证弹窗、页面加载失败）：

const client = new Client({
  puppeteer: {
    headless: false, // 显示浏览器窗口
    args: ['--no-sandbox', '--disable-setuid-sandbox'] // 解决系统权限限制
  }
});

4. 排查网络与代理问题 #

确保网络能正常访问WhatsApp服务器，若使用代理，需给Puppeteer配置代理参数：

const client = new Client({
  puppeteer: {
    args: ['--proxy-server=你的代理地址:端口']
  }
});

5. 重装依赖修复损坏文件 #

若依赖包存在损坏，删除node_modules和package-lock.json后重新执行npm install，确保所有依赖正确安装。

带调试监听的完整示例代码 #

const { Client } = require('whatsapp-web.js');
var qrcode = require('qrcode-terminal');
const client = new Client({
  puppeteer: {
    headless: false,
    args: ['--no-sandbox', '--disable-setuid-sandbox']
  }
});

client.on('qr', (qr) => {
  qrcode.generate(qr, { small: true });
  console.log('QR RECEIVED');
});

client.on('ready', () => {
  console.log('Client is ready!');
});

client.on('auth_failure', (msg) => {
  console.error('认证失败:', msg);
});

client.on('disconnected', (reason) => {
  console.log('客户端断开:', reason);
});

client.on('error', (err) => {
  console.error('客户端错误:', err);
});

client.initialize();

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