使用whatsapp-web.js扫描二维码失败，webVersionCache配置报错求助

初始化代码 #

client = new Client({
    authStrategy: new LocalAuth({
        clientId: phoneNo,
        dataPath: sessionsPath,
    }),
    webVersionCache: {
        type: 'remote',
        remotePath:
            'https://raw.githubusercontent.com/wppconnect-team/wa-version/main/html/2.3000.1014590669-alpha.html',
    },
    puppeteer: {
        headless: true, // or false if you want to see the browser
        args: ['--no-sandbox', '--disable-setuid-sandbox'], // other Chromium flags if needed
    },
    ...clientOpts,
})

问题描述 #

使用上述代码初始化客户端时，指定了wa-version仓库最新提交的Alpha版本远程缓存链接，扫描二维码时报错：
Error: Evaluation failed: TypeError: Cannot read properties of undefined (reading 'default')

原因分析 #

1. 你使用的是Alpha测试版本的WhatsApp Web页面，这类版本存在未修复的兼容性Bug，和whatsapp-web.js的内部逻辑不匹配，导致页面加载后核心对象未正确初始化，触发读取undefined属性的错误。
2. 远程HTML文件可能存在加载不完整、资源路径错误的情况，导致页面关键依赖无法正常加载。

解决办法 #

1. 切换到稳定版本的远程缓存链接

放弃使用Alpha测试版，选择仓库里经过验证的稳定版本链接（比如2.2412.54版本），修改配置如下：

webVersionCache: {
    type: 'remote',
    remotePath: 'https://raw.githubusercontent.com/wppconnect-team/wa-version/main/html/2.2412.54.html',
},

2. 改用本地缓存模式

如果远程链接持续出问题，让客户端自动下载并适配兼容版本，配置改成：

webVersionCache: {
    type: 'local',
    path: './wa-web-cache', // 自定义本地缓存目录
},

3. 更新whatsapp-web.js到最新版

旧版本的whatsapp-web.js可能不兼容最新的WhatsApp Web页面，执行命令更新依赖：

npm update whatsapp-web.js

4. 检查Puppeteer版本兼容性

确保Puppeteer版本和whatsapp-web.js、目标WhatsApp Web页面匹配，避免浏览器内核版本不匹配导致的加载异常。

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