Venom：新一代 WhatsApp 自动化平台的技术架构与实践

Venom 是一个基于 JavaScript 的高性能 WhatsApp 自动化平台，采用 Puppeteer 和纯 TypeScript 重构，提供完整的消息处理、多媒体发送、群组管理和会话持久化功能。

• 原作者/维护者：vynect（Orkestral 团队）
• 来源平台：GitHub
• 原项目名：venom
• 原项目链接：https://github.com/vynect/venom
• 发布时间：2026-06-10

---

Venom 是一个专为 WhatsApp 设计的完整自动化平台，它不是简单的库封装，而是从底层重新构建的高性能系统。该项目采用 JavaScript/TypeScript 开发，基于 Puppeteer 实现对 WhatsApp Web 的完整控制，为开发者提供简洁直观的 API 接口。

与市面上其他 WhatsApp 自动化工具相比，Venom 的核心优势在于其完全重写的架构设计。项目从 83 个源文件精简到仅 6 个核心文件，采用纯 Puppeteer 实现（不再依赖 puppeteer-extra 或 stealth 插件），并升级了 WhatsApp Web 模块（WAWebSocketModel、WAWebConnModel 等）。这种精简带来了更好的可维护性和性能表现。

---

Venom 的技术选型体现了现代 Node.js 开发的最佳实践：

• 运行环境：Node.js 18+（硬性要求）
• 语言：TypeScript 5.7+（启用严格类型检查）
• 浏览器自动化：Puppeteer（Chromium 自动下载）
• 日志系统：Pino（高性能结构化日志）
• 会话管理：内置持久化机制，无需重复扫码

1. 消息处理能力

Venom 支持全类型的消息发送与接收：

文本与富媒体：

• 普通文本消息，支持打字指示器模拟
• 图片发送（本地文件或 Base64 编码）
• 文档、音频、视频文件传输
• 贴纸（静态与动态 GIF）
• 地理位置分享
• 链接预览卡片
• 联系人名片（单张与批量）

交互组件：

• 投票创建（Poll）
• 列表菜单（List Menu）
• 消息回复与转发
• @提及功能

2. 会话与状态管理

Venom 提供了精细化的会话控制机制：

// 会话状态监听
client.onStateChange((state) => {
  // CONFLICT | CONNECTED | DEPRECATED_VERSION | OPENING | PAIRING
  // PROXYBLOCK | TIMEOUT | TOS_BLOCK | UNLAUNCHED | UNPAIRED
});

// 消息送达确认
client.onAck((ack) => {
  // -7 到 4 的完整状态码体系
  // 0 CLOCK | 1 SENT | 2 RECEIVED | 3 READ | 4 PLAYED
});

会话状态涵盖从初始连接到完全就绪的完整生命周期，包括扫码等待、手机端断开、WebSocket 关闭等边缘情况。

3. 群组管理功能

对于企业级应用场景，Venom 提供了完整的群组管理能力：

• 创建群组并邀请成员
• 成员管理（添加、移除）
• 权限控制（提升/降级管理员）
• 群组信息获取（成员列表、管理员、邀请链接）
• 群组描述设置
• 通过邀请码加入群组

4. 事件驱动架构

Venom 采用事件驱动设计，支持多种事件监听：

• onMessage：接收私聊消息
• onAnyMessage：接收所有消息（含群组）
• onLiveLocation：实时位置追踪
• onParticipantsChanged：群组成员变动
• onAddedToGroup：被添加至群组
• onIncomingCall：来电处理

---

npm install venom-bot

import { create } from 'venom-bot';

create({ session: 'venom-bot' }).then((client) => {
  client.onMessage(async (message) => {
    if (message.body === 'hello') {
      await client.sendText(message.from, 'Hey there! 👋 I\'m running on Venom.');
    }
  });
});

首次运行时会生成 QR 码，扫描后即可完成认证。会话会自动持久化，后续启动无需重复扫码。

create({
  session: 'production',
  catchQR: (base64Qr, asciiQR, attempts, urlCode) => {
    console.log(`Scan attempt ${attempts}`);
  },
  statusFind: (status, session) => {
    console.log(`[${session}] Status: ${status}`);
  },
  options: {
    headless: 'new',
    debug: false,
    logQR: true,
    autoClose: 60000,
    addProxy: [''],
  },
  browserInstance: (browser, waPage) => {
    console.log('Browser PID:', browser.process().pid);
  }
});

---