Telegram机器人开发进阶：使用Telegraf框架构建Node.js机器人的完整指南

在Telegram生态中，机器人（Bot）是自动化交互的核心工具。除了Python的python-telegram-bot，Node.js开发者更偏爱轻量高效的Telegraf框架。Telegraf以其简洁的API、强大的中间件机制和灵活的扩展性，成为TypeScript/JavaScript社区中最受欢迎的Telegram Bot框架之一。本文将从零开始，带你掌握Telegraf的核心用法，并给出可直接落地的实战代码。

一、为什么选择Telegraf？

Telegraf的设计哲学与Express.js类似，通过中间件堆栈处理更新。它具备以下优势：

轻量级：无过多依赖，核心包体积小，运行时开销低。
类型支持：官方提供完整的TypeScript类型定义，适合大型项目。
丰富的内置功能：支持命令、回调查询、内联模式、会话管理等。
活跃的社区：持续维护，插件生态完善，如telegraf-ratelimit、telegraf-session等。

二、环境准备与安装

在开始前，请确保已安装Node.js（版本≥12）和npm。然后创建项目目录并安装Telegraf：

mkdir my-bot && cd my-bot
npm init -y
npm install telegraf

获取Bot Token：在Telegram中与@BotFather对话，发送/newbot，按照提示设置名称和用户名，即可获得类似123456789:ABCdef...-xyz的Token。请妥善保管，谨防泄露。

三、第一个Telegraf机器人

创建一个index.js文件，写入以下最小示例：

const { Telegraf } = require('telegraf');
require('dotenv').config();

const bot = new Telegraf(process.env.BOT_TOKEN);

bot.start((ctx) => ctx.reply('欢迎使用Telegraf机器人！'));
bot.help((ctx) => ctx.reply('发送 /help 查看帮助'));

bot.launch();

// 优雅关闭
process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));

将Token配置到.env文件：BOT_TOKEN=你的token。执行node index.js，然后在Telegram中搜索你的机器人用户名，发送/start即可看到回复。

四、核心功能实战

1. 命令处理

除了start和help，我们还可以自定义命令。例如一个简单的天气查询命令：

bot.command('weather', (ctx) => {
  const location = ctx.message.text.split(' ')[1] || '北京';
  ctx.reply(`正在查询 $ 的天气...`);
  // 这里可调用天气API并返回结果
});

2. 消息监听

监听特定文本或类型：

bot.hears('你好', (ctx) => ctx.reply('你好！很高兴见到你。'));
bot.on('sticker', (ctx) => ctx.reply('表情包不错！'));

3. 按钮交互

Telegraf支持内联键盘，实现点击按钮响应：

const { Markup } = require('telegraf');

bot.command('menu', (ctx) => {
  ctx.reply('请选择一个选项：', Markup.inlineKeyboard([
    Markup.button.callback('选项A', 'A'),
    Markup.button.callback('选项B', 'B')
  ])
});

bot.action('A', (ctx) => { ctx.answerCbQuery(); ctx.reply('你选择了A'); });
bot.action('B', (ctx) => { ctx.answerCbQuery(); ctx.reply('你选择了B'); });

4. 发送富媒体

发送图片、文件、音频等：

bot.command('photo', (ctx) => {
  ctx.replyWithPhoto('https://picsum.photos/400/300', { caption: '随机图片' });
});

bot.command('file', (ctx) => {
  ctx.replyWithDocument({ source: './report.pdf' });
});

5. 会话管理

为了记住用户状态，可以使用telegraf-session中间件：

npm install telegraf-session

const session = require('telegraf-session');
bot.use(session());

bot.command('remember', (ctx) => {
  ctx.session.message = '我已记住你的消息';
  ctx.reply('已记录！');
});

bot.command('say', (ctx) => {
  ctx.reply(ctx.session.message || '暂无记忆');
});

五、进阶技巧

1. 中间件复用

利用中间件做权限校验，例如仅允许管理员使用某个命令：

const adminOnly = (ctx, next) => {
  const adminId = Number(process.env.ADMIN_ID);
  if (ctx.from.id === adminId) return next();
  return ctx.reply('无权操作');
};

git
bot.command('secret', adminOnly, (ctx) => ctx.reply('这里是机密'));

2. 错误处理

捕获异常并提示：

bot.catch((err, ctx) => {
  console.error('Bot错误：', err);
  ctx.reply('出错了，请稍后再试');
});

3. 使用Webhook模式

在服务器环境中，长轮询可能不够高效。可以使用Express集成Webhook：

const express = require('express');
const app = express();
app.use(await bot.createWebhook({ domain: 'https://yourdomain.com' }));
app.listen(3000);

六、实战案例：翻译机器人

我们实现一个简单的翻译机器人，调用免费的API（如MyMemory）进行文本翻译。

const axios = require('axios');
bot.command('translate', async (ctx) => {
  const text = ctx.message.text.replace('/translate', '').trim();
  if (!text) return ctx.reply('用法：/translate 要翻译的文本');
  const url = `https://api.mymemory.translated.net/get?q=${encodeURIComponent(text)}&langpair=auto|zh-CN`;
  try {
    const res = await axios.get(url);
    ctx.reply(res.data.responseData.translatedText);
  } catch (err) {
    ctx.reply('翻译失败');
  }
});

七、常见问题与解决方案

Bot无法响应命令：检查Token是否正确，确保网络能访问Telegram，并在代码中正确调用bot.launch()。
Webhook与自签证书：Telegram要求HTTPS，可使用Let's Encrypt或反向代理（如Nginx）处理SSL。
内存占用过高：避免在全局创建巨大对象，合理使用会话存储，可切换至Redis等外部存储。
更新冲突：如果以开发模式运行，请确保唯一的进程在调用getUpdates。

八、总结

Telegraf框架让Node.js开发者能够快速构建出功能丰富、稳定可靠的Telegram机器人。本文介绍了从环境配置到核心API的使用，以及中间件、会话、Webhook等进阶主题。掌握这些基础后，你可以继续探索Telegraf的插件生态，组合更多高级功能。实践出真知，快动手创建你的第一个Telegraf机器人吧！