简介本资源是一款基于Wechaty框架开发的轻量级智能微信群聊机器人助手面向开发者、群管理员及自动化运维爱好者解决疫情常态化下微信群信息过载、关键消息易丢失、多群协同低效等实际管理痛点。压缩包共23个文件含11个核心JS脚本如bot.js、onMessage.js、nCoV.js实现主逻辑与功能模块、6个JSON配置文件含puppet-wechat.memory-card.json等登录与会话持久化数据、1个.env环境配置、1个Dockerfile支持容器化部署整体仅127KB结构紧凑、开箱即用。已有168人学习下载资源附带README.md说明文档、说明文件.txt与附赠资源.docx涵盖部署流程、API调用示例、防撤回原理说明及多群转发策略设计代码模块划分清晰关键功能如疫情数据抓取、天气查询、定时提醒均封装为独立工具函数便于二次开发与功能裁剪。1. 项目缘起为什么我们需要一个“聪明”的微信群机器人几年前我还在一个几百人的技术社区群里当管理员每天光是处理“撤回消息后大家追问说了啥”、“重复回答新人入群问题”、“手动转发疫情/天气信息”这些琐事就耗费了大量精力。当时市面上的一些机器人要么功能单一要么配置复杂要么动不动就“失联”。直到我开始接触 Wechaty 这个框架才真正找到了一个能让我自己动手、丰衣足食的解决方案。这个项目就是基于 Wechaty 框架一步步打磨出来的一个“全能型”微信群聊机器人助手。它不是一个简单的关键词回复工具而是一个集成了智能对话、消息防撤回、实时数据查询、资讯推送、娱乐互动以及多群自动化管理的综合性助手。想象一下你的微信群可以自动播报每日天气在疫情紧张时推送本地风险提示定时提醒群友开会或打卡还能在大家闲聊时插科打诨玩个小游戏。更重要的是作为管理员你能“看见”所有被撤回的消息并对多个群进行统一或差异化的规则设置。这一切的核心都建立在 Wechaty 这个稳定、跨平台的微信机器人 SDK 之上。今天我就把这个项目的完整构建思路、核心代码逻辑以及我踩过的无数个坑毫无保留地分享出来。无论你是想管理自己的兴趣社群还是为企业内部打造一个自动化通知工具这篇文章都能给你提供一条清晰的路径。2. Wechaty 框架选型与基础环境搭建在决定自己造轮子之前我几乎试遍了当时所有能找的微信机器人方案。有基于 Web 协议封装的但更新频繁稳定性堪忧有需要特殊客户端版本的兼容性差。最终选择 Wechaty最根本的原因在于它的设计理念提供一个类似于 Puppeteer 操控浏览器那样的标准化接口来操控微信客户端。这意味着只要微信客户端本身能正常工作机器人就能稳定运行无需关心底层协议是如何变化的。2.1 为什么是 WechatyWechaty 的核心优势在于其“协议无关性”。它通过“Puppet”抽象层支持多种后端协议如 PadLocal、Windows、MacOS 等。对于初学者或追求稳定的开发者我强烈推荐使用PadLocal协议。它是一个基于 iPad 协议的实现相较于 Web 协议它更稳定被封号的风险也相对较低当然任何自动化操作都需谨慎避免高频、营销行为。Wechaty 社区活跃文档齐全遇到问题容易找到解决方案。从技术栈来看Wechaty 主要支持 Node.js 和 Python。考虑到生态丰富度和我个人技术栈我选择了 Node.js 版本。它的异步事件驱动模型非常适合处理微信消息这种高并发的 IO 密集型场景。2.2 项目初始化与核心依赖安装首先确保你的开发环境已经安装了 Node.js建议版本 14 或以上和 npm。然后我们创建一个新的项目目录并初始化。mkdir wechat-bot-assistant cd wechat-bot-assistant npm init -y接下来安装 Wechaty 核心库以及我们项目需要用到的几个关键依赖npm install wechaty wechaty-puppet-padlocal qrcode-terminal npm install axios node-schedule node-cachewechaty: 核心框架。wechaty-puppet-padlocal: PadLocal 协议的 Puppet 实现这是机器人稳定运行的关键。注意PadLocal 服务需要 token早期可能有免费额度现在通常需要自建服务或使用社区提供的服务这部分后面会详细说明。qrcode-terminal: 在终端显示登录二维码方便无头环境部署。axios: 用于发起 HTTP 请求调用天气、疫情等外部 API。node-schedule: 一个功能强大的 Node.js 定时任务库用于实现定时提醒、新闻推送等功能。node-cache: 一个简单内存缓存用于缓存 API 数据如天气避免频繁请求也能用于暂存消息以实现防撤回。2.3 获取并配置 PadLocal Token这是整个项目遇到的第一个也可能是最大的一个“坑”。Wechaty 本身不提供协议实现PadLocal Puppet 需要一个服务端来维持与微信服务器的长连接。你需要获取一个PADLOCAL_TOKEN。早期方案访问 PadLocal 官方 GitHub按照指引部署自己的 PadLocal 网关服务器。这需要一定的服务器运维能力但可控性最高完全免费。当前可行方案由于官方服务的变更目前更常见的做法是使用 Wechaty 社区推荐的其它 Puppet 服务提供商例如wechaty-puppet-wechat4u基于 Web 协议无需 token但稳定性稍差或寻找其他稳定服务商。为了教程的普适性我们以需要 Token 的 PadLocal 为例讲解逻辑如果你使用其他 Puppet初始化方式略有不同。假设你已经通过某种方式获得了YOUR_PADLOCAL_TOKEN我们通过环境变量来配置它避免将敏感信息硬编码在代码中。创建一个.env文件记得加入.gitignorePADLOCAL_TOKENyour_actual_token_here然后在主程序入口我们这样初始化机器人const { WechatyBuilder } require(wechaty); const { PuppetPadlocal } require(wechaty-puppet-padlocal); const QRCode require(qrcode-terminal); require(dotenv).config(); // 加载 .env 文件 const puppet new PuppetPadlocal({ token: process.env.PADLOCAL_TOKEN, }); const bot WechatyBuilder.build({ name: my-assistant-bot, puppet, }) .on(scan, (qrcode, status) { if (status ScanStatus.Waiting) { QRCode.generate(qrcode, { small: true }); console.log(请扫描二维码登录。); } }) .on(login, (user) { console.log(用户 ${user} 登录成功); }) .on(logout, (user) { console.log(用户 ${user} 已登出。); }) .on(error, (error) { console.error(机器人遇到错误, error); }); bot.start() .then(() console.log(机器人启动开始)) .catch(e console.error(机器人启动失败, e));运行这段代码如果一切正常终端会打印出一个二维码用你打算作为机器人的微信扫码登录即可。看到“登录成功”的日志万里长征就走完了第一步。注意扫码登录的本质是机器人接管了这个微信账号的客户端。因此请务必使用一个专门的小号不要用你的主力微信号。同时这个账号在手机微信上会被踢下线这是正常现象。3. 核心功能模块实现详解登录成功后我们的机器人还只是一个“壳”。接下来我们将为它注入灵魂实现标题中提到的各项功能。所有功能都将通过监听 Wechaty 提供的各种事件来实现最主要的就是message事件。3.1 消息监听与自动回复框架所有消息处理的起点都是message事件。我们需要建立一个清晰的消息处理管道根据消息类型、内容、发送者等信息将消息路由到不同的处理函数。const bot WechatyBuilder.build({ ... }); // 接上面的初始化代码 // 引入我们即将编写的各个功能模块 const autoReply require(./modules/autoReply); const antiRecall require(./modules/antiRecall); const dataQuery require(./modules/dataQuery); const newsPush require(./modules/newsPush); const game require(./modules/game); const groupManager require(./modules/groupManager); const scheduler require(./modules/scheduler); bot.on(message, async (msg) { // 1. 防撤回模块最先处理需要记录原始消息 await antiRecall.recordMessage(msg); // 2. 过滤掉自己发送的消息和某些系统消息避免循环回复 if (msg.self() || msg.type() ! bot.Message.Type.Text) { // 非文本消息如图片、语音或自己发的消息暂时跳过文本处理但防撤回仍需记录 return; } const text msg.text().trim(); const room msg.room(); // 是否为群消息 const talker msg.talker(); // 发送者 // 3. 判断消息是否了机器人仅在群聊中 const isMentioned room await msg.mentionSelf(); // 4. 构建上下文对象方便各模块使用 const context { bot, msg, text, room, talker, isMentioned }; // 5. 功能路由 - 按优先级处理 // 优先处理明确指令例如以“#”或“/”开头的命令 if (text.startsWith(#天气) || text.startsWith(#疫情)) { await dataQuery.handle(context); return; } // 处理机器人的消息 if (isMentioned) { const pureText text.replace(/[^ ]\s/g, ).trim(); // 移除标记 context.text pureText; // 可以在这里触发智能对话或特定命令 await autoReply.handleMention(context); return; } // 群管理指令通常需要管理员权限并以特定前缀开头 if (text.startsWith(!禁言) (await isRoomAdmin(room, talker))) { await groupManager.handleMute(context); return; } // 娱乐游戏关键词触发 if ([抽签, 运势, 猜数字].some(keyword text.includes(keyword))) { await game.handle(context); return; } // 最后通用自动回复基于关键词匹配 await autoReply.handleGeneral(context); }); // 辅助函数检查发送者是否为群管理员 async function isRoomAdmin(room, talker) { if (!room) return false; const member await room.member(talker); return member member.admin(); }这个框架是一个责任链模式的简化实现。消息会依次经过各个判断条件一旦某个条件被触发并处理完成就会return避免一条消息被重复处理。这样的结构清晰且易于扩展。3.2 防消息撤回功能的实现原理与坑点防撤回是群里最“喜闻乐见”的功能之一。其原理并不复杂在收到每一条消息的瞬间立刻将其内容、发送者、时间等信息缓存起来。当收到一条“消息撤回”的系统通知时再从缓存中取出原消息内容重新发送到群里。Wechaty 提供了message-recall事件来监听撤回行为。// modules/antiRecall.js const NodeCache require(node-cache); const messageCache new NodeCache({ stdTTL: 600 }); // 缓存10分钟 /** * 记录所有消息 */ async function recordMessage(msg) { const msgId msg.id; const messageInfo { text: msg.text(), type: msg.type(), talkerName: msg.talker()?.name(), roomId: msg.room()?.id, timestamp: new Date(), }; // 以消息ID为键进行存储 messageCache.set(msgId, messageInfo); } /** * 监听消息撤回事件 */ function initRecallListener(bot) { bot.on(message-recall, async (recalledMsgId, newMsgId) { // recalledMsgId 是被撤回的消息ID const originalMsg messageCache.get(recalledMsgId); if (!originalMsg) { console.log(未找到被撤回消息 ${recalledMsgId} 的缓存。); return; } // 找到原消息所在的群 const room originalMsg.roomId ? await bot.Room.find({ id: originalMsg.roomId }) : null; if (!room) { return; // 如果不是群消息或找不到群则忽略 } const recallAnnouncement 【防撤回小助手】\n ${originalMsg.talkerName} 撤回了消息\n “${originalMsg.text}”; await room.say(recallAnnouncement); // 可选从缓存中删除避免重复提示 messageCache.del(recalledMsgId); }); } module.exports { recordMessage, initRecallListener };在主程序中需要在bot.start()之后调用initRecallListener(bot)。踩坑实录缓存策略不能无限制缓存所有消息否则内存会爆炸。stdTTL参数设置了每条缓存的生存时间我设为10分钟因为通常撤回发生在很短的时间内。对于需要长期留存的消息如重要通知应有单独的逻辑处理。消息类型上述示例只处理了文本消息。如果希望防撤回图片、文件等需要调用msg.toFileBox()等方法将媒体文件保存到本地或云存储并在缓存中记录文件路径。这涉及到更复杂的资源管理。性能与隐私在大型活跃群中消息量巨大。频繁的缓存读写可能成为性能瓶颈。同时必须注意用户隐私。我的做法是仅在代码中实现功能对外宣称时模糊处理并且绝不存储或上传消息内容到自己的服务器。系统消息干扰微信还有其它类型的系统消息如“某某修改了群名”需要做好过滤避免误触发。3.3 外部数据查询天气、疫情与新闻这类功能的核心是调用第三方 API并对返回的数据进行格式化以友好、清晰的方式呈现给用户。我们以天气查询为例。首先你需要去一个天气 API 服务平台如和风天气、OpenWeatherMap申请一个免费的 API Key。// modules/dataQuery.js const axios require(axios); const NodeCache require(node-cache); const apiCache new NodeCache({ stdTTL: 1800 }); // 缓存30分钟 const WEATHER_API_KEY process.env.WEATHER_API_KEY; const WEATHER_API_URL https://devapi.qweather.com/v7/weather/now; async function handle(context) { const { msg, text, room } context; if (text.startsWith(#天气)) { const city text.replace(#天气, ).trim() || 北京; // 默认城市 const weatherInfo await getWeather(city); const reply formatWeather(weatherInfo, city); await (room || msg.talker()).say(reply); // 如果在群里回复到群私聊则回复给个人 } // 可以继续扩展 #疫情 等命令 } async function getWeather(cityName) { const cacheKey weather:${cityName}; const cached apiCache.get(cacheKey); if (cached) { console.log(从缓存获取天气数据${cityName}); return cached; } try { // 第一步可能需要先通过城市名获取 locationId这里简化假设直接使用城市名作为参数 // 实际使用中和风天气需要先调用城市搜索API获取locationId const locationResponse await axios.get(https://geoapi.qweather.com/v2/city/lookup?key${WEATHER_API_KEY}location${encodeURIComponent(cityName)}); const location locationResponse.data?.location?.[0]; if (!location) { throw new Error(未找到该城市); } const locationId location.id; // 第二步用 locationId 获取实时天气 const response await axios.get(${WEATHER_API_URL}?key${WEATHER_API_KEY}location${locationId}); const data response.data; if (data.code 200) { apiCache.set(cacheKey, data); return data; } else { throw new Error(data.msg || 天气查询失败); } } catch (error) { console.error(获取天气失败, error); return null; } } function formatWeather(data, city) { if (!data || !data.now) { return 抱歉暂时无法获取【${city}】的天气信息。; } const now data.now; return 【${city}实时天气】\n 天气状况${now.text}\n 当前温度${now.temp}℃\n 体感温度${now.feelsLike}℃\n 风向风力${now.windDir} ${now.windScale}级\n 相对湿度${now.humidity}%\n 更新时间${data.updateTime}; } module.exports { handle };关键点与避坑指南API Key 管理务必通过环境变量 (process.env) 引入 API Key不要写在代码里提交到 Git。请求频率限制免费 API 通常有调用次数限制。缓存是必须的对于天气这种变化不频繁的数据缓存30分钟或1小时完全没问题能极大减少 API 调用。错误处理网络请求可能失败API 可能返回错误。必须用try...catch包裹并在失败时给用户一个友好的提示而不是让机器人沉默或崩溃。数据解析不同 API 返回的数据结构千差万别仔细阅读文档处理好边界情况例如城市不存在、返回数据为空等。格式化回复回复消息要清晰、易读。使用\n换行适当使用符号进行排版。好的格式化能极大提升用户体验。疫情数据查询、新闻资讯推送的逻辑与此类似都是“接收命令 - 调用 API - 处理数据 - 格式化回复”的流程。新闻推送可以结合定时任务模块实现每日定时推送。3.4 定时任务提醒的实现定时任务是自动化机器人的精髓。node-schedule库提供了类似 Cron 的语法非常强大。假设我们需要每天上午9点在指定的群里发送一条工作日提醒。// modules/scheduler.js const schedule require(node-schedule); const { getWeather } require(./dataQuery); // 复用天气查询函数 // 存储需要定时任务的群ID const targetRoomIds new Set(); function initScheduledTasks(bot) { // 任务1工作日早上9点问候并播报天气 const morningJob schedule.scheduleJob(0 9 * * 1-5, async function() { // 周一到周五 9:00 console.log(执行早晨定时任务...); for (const roomId of targetRoomIds) { const room await bot.Room.find({ id: roomId }); if (room) { const weather await getWeather(上海); // 可以配置为每个群不同的城市 const greeting 大家早上好今天是${new Date().toLocaleDateString(zh-CN)}工作日加油\n; const weatherReport weather ? formatWeather(weather, 上海) : ; await room.say(greeting weatherReport); } } }); // 任务2每天下午6点提醒下班示例 const eveningJob schedule.scheduleJob(0 18 * * 1-5, async function() { for (const roomId of targetRoomIds) { const room await bot.Room.find({ id: roomId }); if (room) { await room.say(叮咚~ 下午六点啦别忘了看看今天的任务是否都完成了哦准备下班吧); } } }); // 可以添加更多任务... console.log(定时任务已初始化。); } // 提供一个方法让群管理模块可以添加/移除需要执行任务的群 function addTargetRoom(roomId) { targetRoomIds.add(roomId); } function removeTargetRoom(roomId) { targetRoomIds.delete(roomId); } module.exports { initScheduledTasks, addTargetRoom, removeTargetRoom };在主程序登录成功后 (login事件里)调用scheduler.initScheduledTasks(bot)。进阶技巧动态任务管理你可以设计一个命令如#开启每日提醒让群管理员动态地添加当前群到targetRoomIds集合中实现按需订阅。Cron 表达式node-schedule使用 Cron 表达式非常灵活。* * * * * *表示秒、分、时、日、月、周几。网上有很多 Cron 表达式生成器可以帮助你。任务持久化上述代码中任务列表保存在内存中机器人重启后会丢失。对于生产环境需要将targetRoomIds持久化到数据库或文件中。错误处理定时任务中的异步操作如room.say也可能失败最好用try...catch包裹并记录日志避免一个群失败导致整个任务中断。3.5 多群管理与娱乐互动游戏多群管理的核心在于上下文隔离。机器人需要知道当前消息来自哪个群并应用该群的特定配置如欢迎语、自定义命令开关、管理员列表等。这通常需要一个简单的数据层可以是内存对象、JSON 文件或数据库。// modules/groupManager.js // 使用一个简单的对象模拟群配置存储 const groupConfigs { // roomId: { welcomeMsg: ..., gameEnabled: true, ... } }; async function handleMute(context) { const { msg, text, room } context; // 解析命令例如 “!禁言 某人 10” const args text.split(/\s/); if (args.length 3) return; const targetName args[1].replace(, ); const minutes parseInt(args[2], 10); // 1. 根据 targetName 找到群成员对象 (这里简化实际需要遍历群成员匹配) // 2. 调用 Wechaty 可能的禁言接口注意个人版微信机器人可能无官方禁言API此功能常依赖于协议特性可能不稳定或不可用 // 3. 发送操作结果反馈 await room.say(已尝试对 ${targetName} 禁言 ${minutes} 分钟。); } // 新成员入群欢迎 async function onRoomJoin(room, inviteeList, inviter) { const config groupConfigs[room.id]; if (config config.welcomeMsg) { for (const invitee of inviteeList) { await room.say(${invitee.name()} ${config.welcomeMsg}, invitee); } } } module.exports { handleMute, onRoomJoin, groupConfigs };在主程序中需要监听room-join事件并调用groupManager.onRoomJoin。重要提醒微信个人号协议对于群管理如禁言、踢人的支持非常有限且不稳定。许多看似强大的管理功能实际上依赖于非官方协议或特定客户端版本容易失效。在实现这类功能时务必做好兼容性处理和降级方案并明确告知用户其局限性。娱乐互动游戏是提升群活跃度的利器。实现一个简单的“关键词触发随机响应”游戏很容易。// modules/game.js async function handle(context) { const { msg, text, room } context; if (text.includes(抽签)) { const fortunes [大吉, 中吉, 小吉, 平, 凶]; const result fortunes[Math.floor(Math.random() * fortunes.length)]; await (room || msg.talker()).say(你的今日运势是【${result}】); } if (text.includes(猜数字)) { // 可以维护一个 roomId - { gameState } 的映射实现有状态的游戏 await startGuessNumberGame(context); } } async function startGuessNumberGame(context) { const { room, talker } context; const answer Math.floor(Math.random() * 100) 1; // 将答案和游戏状态与房间或用户关联存储起来 // 然后提示用户开始猜 await room.say(${talker.name()} 数字游戏开始我已经想好了一个1-100之间的数字猜猜看); }游戏的关键在于状态管理。对于简单的无状态游戏如抽签直接随机响应即可。对于有状态游戏如猜数字、成语接龙需要将游戏状态如正确答案、当前回合保存在一个全局对象或数据库中并通过消息内容来更新和判断状态。4. 项目部署、运维与避坑终极指南开发完成只是第一步让机器人7x24小时稳定运行才是真正的挑战。4.1 本地测试与调试技巧在开发阶段建议在本地电脑上运行测试。使用 PM2即使本地运行也推荐使用 PM2 来管理进程。它可以实现崩溃自动重启、日志管理。pm2 start bot.js --name wechat-bot。日志记录不要只用console.log。使用winston或log4js等日志库将日志分级Info, Error, Debug输出到文件和控制台方便排查问题。处理扫码服务器部署时无法显示二维码。可以使用WECHATY_PUPPET_PADLOCAL_TOKEN环境变量并配合一些支持远程扫码的方案如将二维码生成到可访问的 URL或者使用可热登录的 Puppet。4.2 服务器部署方案选择一台海外的 VPS避免国内服务器可能存在的网络问题安装 Node.js 环境。使用 Docker推荐将你的机器人代码 Docker 化可以极大简化环境配置和迁移。编写一个Dockerfile将代码、环境变量打包进去。FROM node:16-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --onlyproduction COPY . . CMD [node, bot.js]使用docker-compose管理更便捷。进程守护在服务器上必须使用进程守护工具。PM2 依然是首选。npm install -g pm2 pm2 start bot.js --name wechat-bot pm2 save pm2 startup # 设置开机自启处理登录状态PadLocal 等 Puppet 通常支持“热登录”即登录一次后Token 会长期有效即使重启机器人。确保你的 Token 文件或环境变量正确配置。如果 Token 失效需要重新扫码。4.3 常见问题与稳定性保障机器人掉线/无响应原因网络波动、微信客户端协议更新、Puppet 服务不稳定。对策使用 PM2 自动重启在代码中监听error和logout事件尝试自动重新初始化考虑使用双 Puppet 备用方案复杂。消息发送失败/频繁原因微信对自动化行为有频率限制。短时间内发送大量消息尤其是相同内容极易被限制功能甚至封号。对策这是红线必须在代码中加入速率限制。例如使用bottleneck库限制向同一个群或联系人发送消息的间隔比如至少间隔 2-3 秒。对于广播消息更要有长达数分钟甚至小时的间隔。封号风险根本原则模拟人类行为低调使用。具体措施避免发送营销、广告、政治类内容避免在短时间内添加大量好友或群聊避免高频互动使用一个“养”了一段时间的、有正常社交记录的微信小号功能以服务、娱乐为主而非营销。依赖更新定期更新wechaty及相关 Puppet 的版本以获取稳定性修复和新特性。但升级前务必在测试环境验证。数据备份如果你的机器人存储了群配置、用户数据等定期备份这些数据。4.4 功能扩展思路这个项目是一个强大的基础框架你可以在此基础上无限扩展接入 ChatGPT/文心一言等大语言模型将autoReply.handleMention或通用回复模块替换为调用大模型 API实现真正的智能对话。自定义技能插件系统设计一个插件架构让每个功能天气、游戏、管理都是一个独立的插件通过配置文件动态加载便于管理和社区贡献。Web 控制面板开发一个简单的 Web 界面用来查看机器人状态、管理定时任务、配置群开关等提升可运维性。对接其他服务通过 Webhook 将微信群消息同步到 Slack、Discord 或你的内部系统实现跨平台通知。构建一个微信机器人就像养一个电子宠物需要持续的维护和调教。从简单的自动回复到复杂的多群管理每一步都会遇到不同的问题。但当你看到它在你设定的规则下流畅地运行为社群带来便利和欢乐时那种成就感是无可替代的。希望这份超详细的指南能帮你少走弯路顺利打造出属于你自己的那个“最聪明”的群助手。本文还有配套的精品资源点击获取