Weixin Bot SDK

独立、轻量级的微信机器人 SDK，让任何 AI/机器人都能通过简单的 API 调用实现微信消息收发。

特性

• 零依赖，不依赖任何框架
• 简单易用的事件驱动 API
• 支持文本、图片、文件、视频、语音消息收发
• 自动下载和解密多媒体消息 (v1.1.0+)
• 扫码登录，自动保存凭证
• 完整的 TypeScript 类型定义

安装

pnpm add @zhoushengdao/weixin-bot

5 分钟快速开始

1. 创建机器人

import { WeixinBot } from "@zhoushengdao/weixin-bot";

const bot = new WeixinBot({
  storageDir: "./data",
});

2. 监听消息

bot.on("message", async (msg) => {
  console.log(`收到：${msg.text}`);
  await bot.sendMessage(msg.from, `你说：${msg.text}`);
});

3. 启动机器人

await bot.start(); // 首次运行会显示二维码

4. 运行

npx tsx bot.ts

用微信扫描终端中的二维码即可连接。

完整示例

import { WeixinBot } from "@zhoushengdao/weixin-bot";

async function main() {
  const bot = new WeixinBot({ debug: true });

  bot.on("ready", () => console.log("已连接"));
  bot.on("error", (err) => console.error("错误：", err));

  bot.on("message", async (msg) => {
    // 处理文本消息
    if (msg.type === "text") {
      await bot.sendMessage(msg.from, `收到：${msg.text}`);
    }

    // 处理图片消息
    if (msg.type === "image" && msg.mediaPath) {
      console.log(`收到图片：${msg.mediaPath}`);
      await bot.sendMessage(msg.from, "收到图片！");
    }

    // 处理文件消息
    if (msg.type === "file" && msg.mediaPath) {
      console.log(`收到文件：${msg.mediaFileName}`);
      await bot.sendMessage(msg.from, `收到文件：${msg.mediaFileName}`);
    }

    // 处理视频消息
    if (msg.type === "video" && msg.mediaPath) {
      console.log(`收到视频：${msg.mediaPath}`);
      await bot.sendMessage(msg.from, "收到视频！");
    }

    // 处理语音消息
    if (msg.type === "voice") {
      console.log(`收到语音：${msg.text}`);
      await bot.sendMessage(msg.from, `收到语音：${msg.text}`);
    }
  });

  await bot.start();
  console.log("机器人运行中... Ctrl+C 退出");
}

main().catch(console.error);

接入 AI

import { WeixinBot } from "@zhoushengdao/weixin-bot";
import OpenAI from "openai";

const bot = new WeixinBot();
const ai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

bot.on("message", async (msg) => {
  const response = await ai.chat.completions.create({
    model: "gpt-4",
    messages: [{ role: "user", content: msg.text }],
  });

  await bot.sendMessage(msg.from, response.choices[0].message.content);
});

await bot.start();

API 概览

| 方法 | 说明 | | ---------------------------- | ------------------------ | | bot.start() | 启动机器人（首次需扫码） | | bot.stop() | 停止机器人 | | bot.sendMessage(to, text) | 发送文本消息 | | bot.sendImage(options) | 发送图片 | | bot.sendFile(options) | 发送文件 | | bot.sendVideo(options) | 发送视频 | | bot.on('message', handler) | 监听消息 |

文档

查看完整文档：docs/README.md

• 快速开始
• API 参考
• 事件处理
• 媒体处理

示例

运行示例程序：

pnpm example

或直接运行某个示例：

node examples/basic-bot.js
node examples/ai-bot.js

开发

克隆仓库

git clone https://github.com/zhoushengdao/weixin-bot.git
cd weixin-bot

安装依赖

pnpm install

开发模式

启动 watch 模式，代码修改后自动编译：

pnpm dev

测试

运行所有测试：

pnpm test

运行单个测试文件：

npx vitest run path/to/test.test.ts

按名称匹配运行测试：

npx vitest run -t "test name"

代码检查

pnpm lint

构建

编译 TypeScript 到 dist/ 目录：

pnpm build

发布到 npm

# 1. 登录 npm（首次需要）
npm login --registry https://registry.npmjs.org

# 2. 发布（scoped 包需要 --access public）
pnpm publish --access public

# 3. 或者发布 beta 版本
pnpm publish --tag beta --access public

发布前会自动执行 pnpm build（通过 prepublishOnly 钩子）。

系统要求

• Node.js >= 22
• 国内网络环境（访问微信 API）

许可证

MIT