🚀 WhatsApp Web 机器人框架
WhatsApp Web 机器人框架是一款强大的工具，可用于控制 WhatsApp 账号，实现消息的收发。它基于 whatsapp-web.js，通过浏览器版 WhatsApp 进行连接。
🚀 快速开始
安装依赖项
项目使用 npm 包管理器进行依赖管理和运行时环境配置。安装所有依赖项：
npm install
使用 Docker
为了方便部署，项目提供了 Docker 镜像。拉取镜像并启动：
docker pull liuhuanjin0927/whatsapp-web-mcp:latest
docker run -it --rm liuhuanjin0927/whatsapp-web-mcp
快速上手
在 main.ts 文件中，你可以看到一个简单的运行示例：
import { WhatsApp } from 'whatsapp-web.js';
import * as WAProto from '@whatsprotypes/core';
async function run() {
const WA = new WhatsApp({
puppeteer: {
executablePath: process.env.CHROME_PATH || undefined,
args: ['--no-sandbox']
},
logLevel: 'info'
});
await WA.start();
console.log('WhatsApp 已启动');
}
run().catch(console.error);
✨ 主要特性
- 消息收发：支持发送和接收文本、图片等消息
- 媒体处理：可以发送和下载图片、音频、文件等媒体内容
- 群组管理：提供群组聊天的创建、加入和退出功能
- 联系人管理：支持添加、删除和搜索联系人
- 日志系统：内置基于 Winston 的强大日志记录功能
📦 安装指南
项目构建
从源代码构建项目：
npm run build
💻 使用示例
基础用法
import { WhatsApp } from 'whatsapp-web.js';
import * as WAProto from '@whatsprotypes/core';
async function run() {
const WA = new WhatsApp({
puppeteer: {
executablePath: process.env.CHROME_PATH || undefined,
args: ['--no-sandbox']
},
logLevel: 'info'
});
await WA.start();
console.log('WhatsApp 已启动');
}
run().catch(console.error);
📚 详细文档
测试
使用 Jest 进行单元测试：
# 执行所有测试
npm test
# 监视模式下运行测试
npm run test:watch
# 生成覆盖报告
npm run test:coverage
格式化与代码质量
使用 ESLint 和 Prettier 维护代码规范：
# 运行检查
npm run lint
# 自动修复问题
npm run lint:fix
# 格式化代码
npm run format
🔧 技术细节
故障排除
集成问题
- Claude Desktop 集成限制：由于 Claude 启动多个进程，无法在命令行模式下直接运行
wweb-mcp。为了解决这个问题，我们将应用拆分为 MCP 模式和 API 模式，以实现与 Claude 的兼容性。
未来计划
- 扩展媒体支持：支持发送视频、音频和文件
- 模板消息：提供常用场景的消息模板
- 高级群组功能：增强的群组管理特性
- 性能优化：提升机器人在高负载情况下的表现
贡献指南
如何贡献代码
- Fork 项目仓库
- 创建新的分支
- 提交代码更改
- 提交 Pull Request
开发注意事项
- 遵循项目的代码规范和风格
- 确保新增功能通过单元测试
- 提供详细的文档说明
日志记录
日志级别
项目支持以下日志级别：
- debug：调试信息
- info：一般信息
- warning：警告信息
- error：错误信息
- critical：严重错误
- fatal：致命错误
默认日志级别为 info。
故障排除指南
常见问题
-
无法连接 WhatsApp 账号
- 确保浏览器已登录目标账号
- 检查网络连接状态
- 查看控制台输出的错误信息
-
Docker 部署失败
- 确保 Docker 服务正在运行
- 检查镜像拉取日志
- 核对端口映射和权限设置
📄 许可证
本项目遵循 MIT License 协议。
感谢使用 WhatsApp Web 机器人框架！如有任何问题或建议，请随时联系我们。