纸飞机App导航 基于 Node.js 的 Telegram 机器人开发教程：从 Hello World 到上线部署

Telegram 机器人可以用于自动回复、群组管理、消息通知、客服接待、内容分发以及业务流程自动化。对于前端或 JavaScript 开发者来说，Node.js 具备生态成熟、异步 I/O 高效、部署方式灵活等优势，非常适合用来构建 Telegram Bot。

本教程将以一个完整的实战流程为主线，从创建机器人、搭建 Node.js 项目开始，逐步实现 Hello World、命令处理、按钮交互、错误处理，并介绍如何使用环境变量和 PM2 将机器人部署到服务器长期运行。

🤖 一、Telegram 机器人开发前的准备工作

开发 Telegram 机器人之前，需要准备一台能够访问 Telegram API 的服务器或本地开发环境，以及 Node.js 运行时。建议使用 Node.js 18 或更高版本，并确保 npm 可以正常执行。

你还需要通过 Telegram 官方的 BotFather 创建机器人并获取 Bot Token。Token 相当于机器人的身份凭证，一旦泄露，其他人就可能控制你的机器人，因此不要将 Token 写入公开代码仓库。

1. 创建 Telegram Bot

在 Telegram 中搜索 @BotFather，发送以下命令创建机器人：

/newbot

按照提示输入机器人的显示名称和用户名，用户名通常必须以 bot 结尾，例如 node_demo_bot。创建完成后，BotFather 会返回一串 Token，请将它保存到密码管理工具或安全的服务器环境变量中。

纸飞机App导航 2. 初始化 Node.js 项目

在终端中创建项目目录，并初始化 npm 配置：

mkdir telegram-node-bot
cd telegram-node-bot
npm init -y
npm install telegraf dotenv

Telegraf 是 Node.js 生态中常用的 Telegram Bot 框架，提供命令监听、中间件、键盘按钮和上下文对象等能力。dotenv 用于将本地环境变量加载到 Node.js 进程中。

🚀 二、实现第一个 Hello World 机器人

纸飞机App导航 在项目根目录创建 .env 文件，用于保存 Bot Token。生产环境中也应该使用同样的环境变量方案，而不是直接把密钥硬编码在 JavaScript 文件中。

BOT_TOKEN=替换成你的Telegram_Bot_Token

接着创建 bot.js，编写最小可运行程序：

require('dotenv').config();

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

const token = process.env.BOT_TOKEN;

if (!token) {
  throw new Error('缺少 BOT_TOKEN 环境变量');
}

const bot = new Telegraf(token);

bot.start((ctx) => {
  ctx.reply('你好，欢迎使用我的 Telegram 机器人！');
});

bot.help((ctx) => {
  ctx.reply('可用命令：/start、/help、/about');
});

bot.command('about', (ctx) => {
  ctx.reply('这是一个基于 Node.js 和 Telegraf 构建的示例机器人。');
});

bot.launch()
  .then(() => console.log('Bot 已启动'))
  .catch((error) => {
    console.error('Bot 启动失败：', error);
    process.exit(1);
  });

process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));

在 package.json 中添加启动脚本，然后运行项目：

npm pkg set scripts.start="node bot.js"
npm start

如果控制台显示 Bot 已启动，说明机器人已经通过 Long Polling 连接 Telegram。此时打开机器人聊天窗口，发送 /start 或 /help，即可看到回复。

💬 三、处理普通消息与用户输入

Telegram Bot 不仅能够识别斜杠命令，还可以监听普通文本消息。Telegraf 会把当前消息封装在 ctx 对象中，你可以通过 ctx.message.text 获取用户输入。

bot.on('text', async (ctx) => {
  const message = ctx.message.text.trim();

  if (message === '你好') {
    await ctx.reply('你好！很高兴认识你。');
    return;
  }

  await ctx.reply(`你发送的内容是：${message}`);
});

实际项目中，建议对用户输入进行长度限制、格式校验和异常处理。如果机器人会调用数据库、第三方接口或 AI 服务，还应该设置超时机制，避免单个请求长时间占用处理流程。

使用 Inline Keyboard 创建交互按钮

按钮可以减少用户输入成本，也能让机器人菜单更加清晰。下面的代码会发送两个内联按钮，并根据用户点击的回调数据执行不同逻辑。

bot.command('menu', async (ctx) => {
  await ctx.reply('请选择一个功能：', {
    reply_markup: {
      inline_keyboard: [
        [{ text: '查看状态', callback_data: 'status' }],
        [{ text: '联系管理员', callback_data: 'contact_admin' }]
      ]
    }
  });
});

bot.action('status', async (ctx) => {
  await ctx.answerCbQuery();
  await ctx.editMessageText('当前机器人运行正常。');
});

bot.action('contact_admin', async (ctx) => {
  await ctx.answerCbQuery();
  await ctx.editMessageText('请发送你的问题，管理员会尽快处理。');
});

调用 answerCbQuery() 很重要，它可以结束 Telegram 客户端上的按钮加载状态。对于会修改原消息的操作，可以使用 editMessageText()，这样界面会更加简洁。

🛡️ 四、机器人安全与稳定性设计

Telegram Bot 一般会接收来自外部用户的输入，因此不能只关注功能是否可用，还要考虑恶意请求、刷屏和资源消耗。建议为高频命令增加权限判断、频率限制和日志记录。

如果某个功能仅允许管理员执行，可以通过用户 ID 进行校验。不要仅凭用户名判断身份，因为用户名可能被修改，而数字型 Telegram User ID 更适合作为权限依据。

const ADMIN_IDS = new Set(
  (process.env.ADMIN_IDS || '')
    .split(',')
    .map((id) => id.trim())
    .filter(Boolean)
);

bot.command('admin', async (ctx) => {
  const userId = String(ctx.from.id);

  if (!ADMIN_IDS.has(userId)) {
    await ctx.reply('你没有权限执行此命令。');
    return;
  }

  await ctx.reply('管理员功能已开放。');
});

同时，在 .gitignore 中加入环境变量文件，避免提交到 Git 仓库：

node_modules/
.env
*.log

错误处理也应集中配置，避免 API 异常导致进程直接退出。开发阶段可以输出详细日志，生产环境则应隐藏 Token、用户隐私和第三方服务密钥。

bot.catch((error, ctx) => {
  console.error(`处理更新失败，类型：${ctx.updateType}`, error);
});

☁️ 五、使用 PM2 部署到 Linux 服务器

本地运行适合开发调试，但终端关闭后进程通常会停止。部署到云服务器后，可以使用 PM2 管理 Node.js 进程，让机器人在后台运行，并在异常退出后自动重启。

首先安装 PM2，并将项目代码上传到服务器：

npm install -g pm2
npm install --production
pm2 start bot.js --name telegram-bot

随后使用以下命令查看运行状态和日志：

pm2 status
pm2 logs telegram-bot
pm2 restart telegram-bot
pm2 save
pm2 startup

pm2 startup 会生成系统启动配置。按照终端提示执行对应命令后，服务器重启时机器人也可以自动恢复运行。

Long Polling 与 Webhook 如何选择

本教程使用的是 Long Polling，它配置简单，适合入门、内部工具和访问量较小的机器人。Webhook 更适合生产环境中的高并发服务，但通常需要 HTTPS 域名、反向代理和更完整的网络配置。

如果服务器网络不稳定，或者机器人需要和现有 Web 服务统一管理，可以考虑使用 Webhook。无论采用哪种方式，都应该监控进程状态、接口错误率和 Telegram API 的响应情况。

🧪 六、上线前的测试清单

上线前需要使用不同账号测试 /start、/help、/menu 等命令，确认普通用户和管理员用户获得的权限符合预期。还要测试空消息、超长文本、重复点击按钮以及第三方接口不可用等异常场景。

如果机器人用于群组管理，还需要在群组中授予必要权限，并检查隐私模式设置。机器人可能无法读取群组中的所有普通消息，这是 Telegram 的权限和隐私机制所决定的。

纸飞机App导航 此外，应定期轮换密钥、限制服务器 SSH 登录来源、更新 Node.js 依赖，并保留必要的运行日志。对于涉及支付、账号信息或个人数据的机器人，还应明确数据保存周期和访问权限。

❓ 常见问题解答（FAQ）

Node.js Telegram 机器人必须购买服务器吗？

开发和测试阶段不需要购买服务器，在本地电脑运行即可。正式使用时建议部署到稳定的云服务器或容器平台，确保机器人能够持续访问 Telegram API。

Bot Token 泄露后应该怎么办？

应立即在 BotFather 中使用 /revoke 撤销旧 Token，并生成新的凭证。随后检查代码仓库、服务器日志和环境变量，确认旧 Token 没有继续残留。

机器人为什么收不到群组普通消息？

纸飞机App导航 常见原因是 BotFather 开启了隐私模式，或者机器人没有被正确加入群组。可以在 BotFather 中检查 /setprivacy 设置，并根据业务需求授予机器人必要的群组权限。

Long Polling 适合生产环境吗？

纸飞机App导航 对于低并发、功能相对简单的机器人，Long Polling 完全可以用于生产环境。若需要更高吞吐量、更清晰的网络入口或统一接入现有后端服务，则建议进一步采用 Webhook。

如何继续扩展这个机器人？

你可以继续接入 SQLite、MySQL 或 PostgreSQL 保存用户数据，也可以增加定时任务、文件处理、群组权限管理和支付功能。建议先拆分命令处理、业务服务和数据访问模块，再逐步扩大功能范围，避免所有逻辑集中在一个文件中。

通过 Node.js 和 Telegraf，你已经完成了从创建机器人到上线运行的基础闭环。后续开发应始终围绕清晰的交互、可靠的异常处理、严格的密钥保护和可观测的部署流程展开，这些因素决定了 Telegram 机器人能否真正稳定服务用户。