当使用 whatsapp-web.js 时，client.on('ready') 回调未执行，仅 qr 事件正常触发，常见于官方库存在兼容性缺陷或已知 Bug 的版本；临时解决方案是切换至社区修复分支。
当使用 whatsapp-web.js 时，`client.on('ready')` 回调未执行，仅 `qr` 事件正常触发，常见于官方库存在兼容性缺陷或已知 bug 的版本；临时解决方案是切换至社区修复分支。
在基于 whatsapp-web.js 开发 WhatsApp 自动化应用时，开发者常遇到 ready 事件永不触发的问题：QR 码可正常生成并成功扫码登录，控制台输出 "QR RECEIVED"，但后续 Client is ready! 日志始终不出现，导致后续业务逻辑（如消息监听、自动回复等）无法启动。
该问题并非代码逻辑错误，而是由库本身在特定环境（如新版 Chromium 内核、WhatsApp Web 前端更新后）中对 authState 状态变更的监听失效所致。官方 v1.24.x 及更早稳定版中存在一个已知缺陷：initialize() 后客户端未能正确识别认证完成状态，从而跳过 ready 事件广播。
✅ 经验证的有效修复方案如下：
-
卸载当前版本：
npm uninstall whatsapp-web.js
-
在 package.json 中强制指定已修复的社区分支（由开发者 Julzk 维护的 hotfix 分支）：
"dependencies": { "whatsapp-web.js": "https://github.com/Julzk/whatsapp-web.js/tarball/jkr_hotfix_7" } -
重新安装依赖：
npm install
⚠️ 注意事项：
- 该分支为非官方维护版本，适用于紧急上线场景；建议定期关注 whatsapp-web.js 官方 GitHub 的 main 分支更新，待正式版修复后及时回归。
- 若使用 TypeScript，需同步检查类型声明兼容性，必要时手动补充缺失接口（如 jkr_hotfix_7 分支暂未发布完整 @types）。
- 避免在生产环境长期依赖 GitHub tarball 地址——其 CDN 可能存在缓存或访问延迟，推荐 fork 后托管至私有 registry。
? 补充调试建议：
可在初始化后添加状态监听，辅助诊断流程卡点：
client.on('authenticated', () => console.log('Authenticated'));
client.on('auth_failure', msg => console.error('Auth failed:', msg));
client.on('disconnected', reason => console.warn('Disconnected:', reason));
若 authenticated 触发但 ready 不触发，则进一步确认为该 Bug 表现；若连 authenticated 也无响应，请检查 Puppeteer 启动参数、网络代理或 WhatsApp 账号是否被限制登录。
综上，ready 事件失灵本质是 SDK 层状态机同步异常，而非用户代码缺陷。采用经验证的修复分支可快速恢复功能完整性，是当前最务实的工程实践方案。
