Telegram Bot 开发完全指南:从创建到部署
想让 Telegram 帮你自动回复消息、推送通知、管理群组,甚至接入 AI 对话?这一切的起点,都是创建一个属于你自己的 Telegram Bot。
好消息是,Telegram 的 Bot API 完全免费、文档完善、生态丰富。从注册到写出第一个能跑的机器人,最快 10 分钟就能搞定。
这篇文章从零开始,带你走完 Telegram Bot 开发的完整流程。
Telegram 机器人能做什么
在动手之前,先了解一下 Telegram Bot 的能力边界——它能做的事比你想象的多得多:
| 场景 | 示例 |
|---|---|
| 自动回复 | 客服机器人、FAQ 自动应答 |
| 内容推送 | 新闻聚合、RSS 订阅、价格监控 |
| 群组管理 | 自动踢人、关键词过滤、入群验证 |
| 工具集成 | GitHub 通知、CI/CD 状态推送、服务器监控 |
| AI 对话 | 接入 ChatGPT/Claude API,打造私人 AI 助手 |
| Mini App | 在 Telegram 内运行完整的 Web 应用 |
| 支付系统 | 通过 Telegram Stars 销售数字商品 |
Telegram Bot 与普通用户账号有几个关键区别:Bot 不能主动发起对话(用户必须先 /start),没有「最后在线」状态,且头像旁会显示「bot」标签。
准备工作
开始之前,确认你已经具备:
- 一个 Telegram 账号:没有的话先到 telegram.org 下载客户端注册
- 基本编程能力:本文提供 Python 和 Node.js 两种方案,选一个你熟悉的
- 一台能联网的电脑:开发阶段本地运行即可,后续可部署到服务器
如果你在中国大陆,访问 Telegram 需要代理。确保你的开发环境也能正常连接 Telegram API(api.telegram.org)。
通过 BotFather 创建机器人
所有 Telegram Bot 都通过官方的 @BotFather 创建——它本身就是一个机器人,用对话的方式管理你的所有 Bot。
注册新 Bot
-
在 Telegram 中搜索
@BotFather,或直接点击 t.me/botfather -
发送
/start开始对话 -
发送
/newbot创建新机器人 -
BotFather 会问你两个问题:
- Bot 的显示名称:任意取,比如
我的工具箱 - Bot 的用户名:必须以
bot结尾,比如my_toolbox_bot
- Bot 的显示名称:任意取,比如
-
创建成功后,BotFather 会返回一个 API Token,格式类似:
这个 Token 是你机器人的「身份证 + 钥匙」,任何拥有它的人都能完全控制你的 Bot。绝对不要把它提交到 Git 仓库、发到群聊里、或写在公开代码中。使用环境变量存储是最佳实践。
配置 Bot 信息
创建完成后,可以继续用 BotFather 完善 Bot 的信息:
| 命令 | 作用 |
|---|---|
/setdescription | 设置 Bot 描述(用户点开 Bot 时看到) |
/setabouttext | 设置「关于」信息 |
/setuserpic | 上传 Bot 头像 |
/setcommands | 定义命令列表(用户输入 / 时自动提示) |
/mybots | 管理你所有的 Bot |
/deletebot | 删除一个 Bot |
建议至少设置 /setcommands,让用户知道你的 Bot 支持哪些操作:
选择开发语言和框架
Telegram Bot API 是标准的 HTTP API,理论上任何语言都能对接。但使用成熟的框架能帮你省掉大量样板代码。
以下是主流选择:
| 语言 | 框架 | 特点 |
|---|---|---|
| Python | python-telegram-bot | 社区最大,文档丰富,asyncio 原生支持 |
| Node.js / TypeScript | grammY | 现代设计,插件生态好,支持 Deno |
| Node.js | Telegraf | 老牌框架,生态成熟 |
| Go | telebot | 性能好,适合高并发场景 |
| Java | TelegramBots | 官方教程推荐 |
本文重点介绍 Python(python-telegram-bot) 和 Node.js(grammY) 两种方案,选你熟悉的跟着做。
用 Python 编写你的第一个 Bot
环境准备
确保你安装了 Python 3.10+(python-telegram-bot 的最新版本要求):
创建项目目录并安装依赖:
编写回声机器人
先从最简单的「回声」Bot 开始——用户发什么,Bot 就回什么:
设置环境变量并运行:
现在在 Telegram 中给你的 Bot 发消息,它会原样回复。
添加命令处理
实际应用中,Bot 通常通过 /command 响应不同操作:
添加内联键盘
内联键盘(Inline Keyboard)让用户可以通过按钮交互,体验比纯文本好得多:
用 Node.js 编写 Bot
如果你更熟悉 JavaScript/TypeScript,grammY 是当前最推荐的框架——设计现代、类型完善、支持 Telegram Bot API 9.6(2026 年 4 月更新)。
环境准备
创建 .env 文件存储 Token:
记得把 .env 加入 .gitignore,永远不要将 Token 提交到版本控制。
基础实现
创建 bot.js:
在 package.json 中添加 "type": "module",然后运行:
内联键盘
grammY 的键盘 API 非常简洁:
部署你的机器人
开发阶段用 polling(轮询)模式很方便,但生产环境推荐使用 Webhook 模式——更高效、更实时。
Polling vs Webhook
| 对比项 | Polling(轮询) | Webhook |
|---|---|---|
| 工作方式 | Bot 主动向 Telegram 拉取更新 | Telegram 主动推送更新到你的服务器 |
| 延迟 | 取决于轮询间隔,通常 1-2 秒 | 几乎实时 |
| 资源占用 | 持续消耗(即使没有消息) | 按需触发 |
| 适用场景 | 本地开发、低流量 Bot | 生产环境、高流量 Bot |
| 要求 | 无 | 需要公网 HTTPS 地址 |
使用 Webhook 模式(Python)
使用 Webhook 模式(grammY + Express)
部署选项
根据你的需求选择合适的部署方式:
| 方式 | 优势 | 适合场景 |
|---|---|---|
| VPS(Linux 服务器) | 完全掌控,长期稳定 | 需要 24/7 运行的 Bot |
| Vercel / Cloudflare Workers | 免费额度,自动扩缩 | 低频调用的轻量 Bot |
| Docker + 任意云平台 | 一致性好,易迁移 | 团队协作、多 Bot 管理 |
| Railway / Render | 部署简单,免费入门 | 个人项目快速上线 |
如果你有 VPS,推荐用 systemd 管理 Bot 进程,确保崩溃自动重启、开机自启动:
进阶功能探索
掌握基础之后,还有很多进阶能力值得探索:
对话状态管理
处理多轮对话(比如收集用户输入的表单):
限流与权限控制
防止滥用,限制调用频率:
接入 AI 对话
把 Bot 变成 AI 助手:
定时任务
定期执行操作(如每日推送):
常见问题与排错
Bot 没有响应
检查清单:
- Token 是否正确?复制时是否多了空格?
- 网络能否访问
api.telegram.org?(国内需要代理) - 代码是否有未捕获的异常?添加错误日志:
Webhook 收不到消息
- 确认 URL 是 HTTPS(Telegram 不接受 HTTP)
- 确认端口开放(Telegram 只支持 443、80、88、8443)
- 用 Telegram API 检查 webhook 状态:
消息发送失败
- 检查是否被用户 block 了(会返回 403 错误)
- 检查是否超出频率限制(群组每分钟 20 条,私聊每秒 1 条)
- 长消息注意 4096 字符限制,超出需要分片发送
群组中 Bot 不响应
Bot 默认在群组中不接收所有消息。解决方案:
- 通过 BotFather 发送
/setprivacy→ 选择Disable - 或者只通过
/command和@bot_username方式触发
总结
创建一个 Telegram Bot 的完整流程:
Telegram Bot API 的能力远不止本文涉及的这些。当你的 Bot 跑起来之后,建议深入阅读:
动手试试吧——创建你的第一个 Bot,也许就是你下一个自动化利器的起点。