pyTelegramBotAPI：写 Telegram 机器人最省事的 Python 库

pyTelegramBotAPI：写 Telegram 机器人最省事的 Python 库

做 Telegram 机器人开发，绕不开 Bot API。但直接调 HTTP 接口太繁琐，参数拼装、响应解析、轮询管理，每一步都是重复劳动。pyTelegramBotAPI 这个库把这些脏活全包了，让你只关心业务逻辑。

项目 Star 数 8700 多，维护时间超过十年，算得上 Telegram Bot 生态里最老牌的 Python 库之一。支持 Python 3.10 到 3.14，包括 PyPy。安装就一行 pip 命令，没有任何额外依赖。

上手门槛低

一个回显机器人，十行代码搞定。创建 TeleBot 实例，注册消息处理器，调用 infinity_polling()，完事。不需要理解异步、不需要配置 Webhook，对新手来说很友好。

消息处理器用装饰器声明，支持按命令过滤、按内容类型过滤、按正则匹配过滤、按自定义函数过滤。多个处理器可以叠加，按声明顺序依次匹配。这个设计直觉清晰，写起来没什么心智负担。

同步和异步都支持

库提供两个核心类：TeleBot 负责同步，AsyncTeleBot 负责异步。大部分 API 方法名字一样，只是异步版本需要 await。如果你的机器人并发量不大，同步版本足够用。如果需要处理大量消息或者对接异步框架，切到 AsyncTeleBot 就行，不用换库。

功能覆盖面广

Telegram Bot API 的主要能力它都封装了：发消息、发文件、处理回调查询、Inline 模式、支付、投票、论坛话题管理。还支持中间件机制，可以在消息到达处理器之前做拦截和预处理。自定义过滤器也方便，写个 lambda 或者普通函数传进去就行。

高级用法方面，支持本地 Bot API Server 部署、Webhook 模式、代理配置、线程数控制。文档在 ReadTheDocs 上有中英文版本，写得比较全。

实际使用体验

我用它写过几个小机器人，整体感受是稳定。API 覆盖全，遇到 Telegram 新增的接口类型，库更新也比较及时。社区活跃，GitHub 上 Issue 响应速度可以。

缺点也有。库的设计偏传统，没有类型提示（type hints），IDE 补全体验一般。文档虽然全，但示例代码有些地方不够新，跟最新版 API 对不上。另外异常处理这块，网络断开重连的机制需要自己额外处理，库本身没有内置完善的重试策略。

适合什么场景

个人项目、中小团队的 Telegram 机器人，用这个库开发效率最高。不需要折腾底层 HTTP 调用，也不需要关心轮询和 Webhook 的细节。如果你对异步性能有极端要求，可以考虑 python-telegram-bot 那个库，但论上手速度和 API 覆盖度，pyTelegramBotAPI 是个扎实的选择。

和 API 覆盖度，pyTelegramBotAPI 是个扎实的选择。