扫码登录的底层流程与时间窗口
从浏览器打开 web.whatsapp.com 到手机端确认，中间经历三个由不同端控制的阶段，每个阶段都有独立的超时限制。理解这些限制可以避免在错误的方向上反复尝试。
- 二维码生成（浏览器端）：页面加载后由前端 WebSocket 连接向服务端请求一次性二维码，有效期通常为 20 秒。超时后二维码区域会显示刷新按钮，旧二维码立即失效。
- 扫码与密钥交换（手机端）：手机相机识别二维码后，会在本地生成一对临时密钥，并通过已建立的移动网络连接把公钥部分上传。这一步在手机端表现为「正在登录」的转圈状态，一般持续 2 到 8 秒，取决于手机网络的上行质量。
- 浏览器确认（浏览器端）：密钥交换完成后，浏览器端会收到一个加密的会话载荷，并写入 IndexedDB 与 localStorage。写入完成后页面才会跳转到聊天列表。如果此时关闭标签页，会话不会保留，需要重新扫码。
一个常见误区是认为二维码可以截图后稍后使用。实际上二维码绑定的是当前浏览器标签页的 WebSocket 会话，复制到另一台设备或另一个标签页都无法完成握手，服务端会直接拒绝。另一个常见错误是在手机端点击「取消」后继续盯着浏览器页面等待，此时浏览器端不会收到任何状态更新，只能等二维码自然过期。
多设备同步机制对登录态的影响
WhatsApp 网页版属于「已关联设备」体系，与手机端是并列的客户端，而不是手机的镜像。这意味着登录态的生命周期由服务端统一管理，手机端离线不会立刻导致网页版退出，但会影响部分功能的可用性。
- 会话保持：一次成功登录后，网页版会获得一个长期凭证，多数情况下可以保持 14 天 免扫码，具体天数由服务端策略决定，用户无法在界面上修改。
- 手机离线时的行为：消息仍可通过网页版收发，但「联系人信息刷新」「群成员列表更新」等操作会延迟，直到手机端重新上线并完成一次同步。
- 设备数量上限：一个账号通常最多同时关联 4 台 已关联设备（含网页版、桌面版、平板端）。达到上限后，新登录会被拒绝，需要先在手机端「已关联设备」列表中移除一台。
- 退出传播：在手机端移除某台设备后，该设备的网页版会在下一次心跳（通常 30 秒内）收到失效通知并跳回二维码页。
开发者需要注意，网页版的会话凭证与浏览器指纹无关，清理站点数据会直接销毁本地凭证。如果使用自动化工具反复清理 storage，会频繁触发重新扫码，进而可能触发服务端的频率限制。
常见报错与浏览器环境检查清单
登录失败时，页面给出的提示往往很简短，但背后的原因可以按可控性排序排查。下面列出高频现象与对应的检查项。
| 现象 | 可能原因 | 检查动作 |
|---|---|---|
| 二维码区域持续空白 | WebSocket 被代理或防火墙拦截 | 检查是否启用企业代理，确认 wss 连接未被中间人替换证书 |
| 扫码后长时间停在「正在登录」 | 手机上行网络差或系统时间偏差超过 5 分钟 | 校准手机与电脑的系统时间，切换手机网络后重试 |
| 提示浏览器不受支持 | User-Agent 被插件篡改或内核版本过低 | 使用 Chrome 90+、Edge 90+、Firefox 88+ 或 Safari 14+，禁用修改 UA 的扩展 |
| 登录后立即退回二维码页 | 本地存储被隐私插件定期清除 | 把 web.whatsapp.com 加入白名单，关闭「关闭标签页时清理数据」 |
浏览器环境检查清单建议按以下顺序执行：第一，确认没有启用会重写 document.cookie 或拦截 IndexedDB 的扩展；第二，在开发者工具的 Application 面板确认 IndexedDB 中存在以 wawc 开头的数据库；第三，在 Network 面板过滤 ws，确认至少有一条处于 101 Switching Protocols 状态的连接；第四，检查系统时间与 NTP 服务器偏差，超过 5 分钟会导致签名校验失败。完成这四项后仍无法登录，再考虑网络层问题，而不是反复刷新页面。