aiogram 入门实战：用完全异步的 Python 框架快速构建 Telegram Bot-平芜编程栈

后端
即时通讯
API设计

【免费下载链接】aiogram

aiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio

项目地址：https://gitcode.com/gh_mirrors/ai/aiogram

aiogram是一个基于 Python 3.10+ 与asyncio、aiohttp构建的现代全异步 Telegram Bot API 框架。本文以官方文档首页（docs/index.rst）为核心骨架，完整解析其中收录的“简单用法”与“不使用 Dispatcher 的用法”两个官方示例，并深入仓库源码揭示事件分发、Bot 会话与默认属性的底层原理。读完本文，你将掌握从零搭建一个可用 Telegram Bot、并理解其内部运行机制的全部技能。

框架概览：aiogram 是什么

以下内容摘自官方文档首页（即 README.rst，由 docs/index.rst 通过.. include::指令直接引入）：

aiogramis a modern and fully asynchronous framework for Telegram Bot API written in Python 3.10+ usingasyncioandaiohttp。

官方文档首页开宗明义：aiogram 是专为 Telegram Bot API 设计的全异步框架，底层基于 Python 标准库asyncio与高性能 HTTP 客户端aiohttp。这意味着所有网络请求与事件处理都在同一个事件循环内协作调度，天然适合高并发消息场景。

核心特性

异步原生：基于asyncio（PEP 492 语法），全程async/await编写；
类型提示完备：提供完整类型标注（PEP 484），可直接与mypy等静态检查工具配合；
支持 PyPy：不仅限于 CPython 运行时；
紧跟 Bot API 更新：当前支持 Telegram Bot API 10.3，并随官方 API 迭代快速同步；
自动生成集成代码：Bot API 集成代码由tg-codegen自动生成，API 更新时可轻松重新生成；
更新路由（Blueprints）：基于 Router/Dispatcher 的事件路由体系；
内置有限状态机（FSM）：支持复杂对话流程编排；
强大的 magic filters：声明式过滤器，简化事件筛选；
中间件机制：同时支持入站更新与 API 调用两层中间件；
Webhook 内回复：支持 Telegram 官方推荐的 Webhook 响应式回复（Replies into Webhook）；
集成 I18n/L10n：基于 GNU Gettext（或 Fluent）的多语言支持。

注意：官方文档明确提示，使用 aiogram 前最好具备asyncio的基础经验。

快速起步：安装

在运行示例代码前，需要先安装框架。根据官方安装文档 docs/install.rst：

# 从 PyPI 安装（推荐，始终为最新稳定版） pip install -U aiogram

Arch Linux 用户也可以从系统仓库安装，但官方文档特别警告该仓库包可能过时，建议优先使用 PyPI 版本：

# Arch Linux 系统仓库（可能不是最新版） pacman -S python-aiogram

需要体验最新开发版特性时，可直接从 GitHub 的dev-3.x分支安装：

pip install https://github.com/aiogram/aiogram/archive/refs/heads/dev-3.x.zip

简单用法：官方 echo_bot 完整剖析

docs/index.rst通过.. literalinclude:: ../examples/echo_bot.py将 examples/echo_bot.py 全文引入文档，这是 aiogram 官方推荐的入门第一课——一个“回声机器人”（把收到的消息原样返回）。下面逐段深入讲解。

导入与 Token 获取

import asyncio import logging import sys from os import getenv from aiogram import Bot, Dispatcher, html from aiogram.client.default import DefaultBotProperties from aiogram.enums import ParseMode from aiogram.filters import CommandStart from aiogram.types import Message # Bot token can be obtained via https://t.me/BotFather TOKEN = getenv("BOT_TOKEN")

关键点：

Bot：封装了与 Telegram Bot API 交互的客户端（aiogram/client/bot.py 中的Bot类）；
Dispatcher：事件分发器，负责接收并路由 updates（aiogram/dispatcher/dispatcher.py）；
html：HTML 文本装饰工具，从 aiogram/utils/text_decorations.py 导出的html_decoration实例，在 aiogram/init.py 中注册为顶层导出html；
CommandStart：预置的/start命令过滤器（aiogram/filters/command.py）；
Token 通过环境变量BOT_TOKEN传入，可用 @BotFather 创建机器人获取。

注册路由：Dispatcher 与装饰器

dp = Dispatcher() @dp.message(CommandStart()) async def command_start_handler(message: Message) -> None: """ This handler receives messages with `/start` command """ await message.answer(f"Hello, {html.bold(message.from_user.full_name)}!")

这段代码展示了 aiogram 的核心编程范式——装饰器式事件注册：

创建Dispatcher实例；
用@dp.message(CommandStart())注册处理函数：只有当消息触发CommandStart过滤器（即用户发送/start命令）时才会调用该 handler。从源码看，CommandStart是Command的子类，构造时固定绑定命令名"start"、前缀"/"，还额外支持deep_link（深链参数）、ignore_case、ignore_mention等选项（aiogram/filters/command.py）；
处理函数签名接收Message对象，返回None。

message.answer(...)是Message对象提供的方法快捷别名。从 aiogram/types/message.py 的源码注释可以看到，它是aiogram.methods.send_message.SendMessage的 shortcut：调用时会自动填充chat_id、message_thread_id、business_connection_id等字段，因此无需再手动指定聊天 ID——这正是“在事件上下文中回复”的便利之处。

html.bold(...)会将文本包裹为<b>...</b>标签。从 aiogram/utils/text_decorations.py 的实现看，bold通过_tag(self.BOLD_TAG, value)生成 HTML 标签，该文件还提供italic、code、pre、underline、strikethrough、spoiler、quote、link等系列装饰方法。需要说明的是：HTML 标签只有配合ParseMode.HTML才生效，这正是下文DefaultBotProperties(parse_mode=ParseMode.HTML)的用途。

通用消息处理器：echo 逻辑

@dp.message() async def echo_handler(message: Message) -> None: """ Handler will forward receive a message back to the sender By default, message handler will handle all message types (like a text, photo, sticker etc.) """ try: # Send a copy of the received message await message.send_copy(chat_id=message.chat.id) except TypeError: # But not all the types is supported to be copied so need to handle it await message.answer("Nice try!")

@dp.message()不带任何过滤器，表示匹配所有消息类型（文本、图片、贴纸等）。处理逻辑：

优先调用message.send_copy(chat_id=message.chat.id)将收到的消息“原样拷贝”发回。注意 aiogram/types/message.py 源码明确指出：send_copy并不调用Bot API 中名为copyMessage的方法，而是 aiogram 在 API 提供该能力之前就实现的历史方法，它按消息类型分发到对应的SendAnimation、SendAudio、SendPhoto、SendVideo、SendMessage等 17 种发送方法之一，并返回发送出的消息对象；
由于并非所有消息类型都支持拷贝（如部分特殊内容），捕获TypeError后回一句"Nice try!"兜底。

主函数：启动轮询

async def main() -> None: # Initialize Bot instance with default bot properties which will be passed to all API calls bot = Bot(token=TOKEN, default=DefaultBotProperties(parse_mode=ParseMode.HTML)) # And the run events dispatching await dp.start_polling(bot) if __name__ == "__main__": logging.basicConfig(level=logging.INFO, stream=sys.stdout) asyncio.run(main())

这段启动代码包含两个重要概念：

（1）Bot与默认属性

Bot(token=..., default=DefaultBotProperties(parse_mode=ParseMode.HTML))。从 aiogram/client/bot.py 的构造逻辑可以看到：

token会先经过validate_token(token)校验，格式非法时抛出TokenValidationError；
session未显式传入时，自动创建AiohttpSession()；
default未传入时自动取DefaultBotProperties()空实例；
若在kwargs中传入旧的parse_mode、disable_web_page_preview、protect_content参数，会直接抛出TypeError，并提示改用default=DefaultBotProperties(...)——这是 3.7.0 版本引入的破坏性变更。

DefaultBotProperties（aiogram/client/default.py）是一个 dataclass，承载会被传播到所有 API 调用的默认属性，包括：

字段	说明
`parse_mode`	消息默认解析模式（`ParseMode.HTML`/`ParseMode.MARKDOWN_V2`等）
`disable_notification`	静默发送消息，用户收到通知但不发声
`protect_content`	禁止内容被转发/复制
`allow_sending_without_reply`	允许无回复目标时仍发送
`link_preview`/`link_preview_is_disabled`/`link_preview_prefer_small_media`/`link_preview_prefer_large_media`/`link_preview_show_above_text`	链接预览相关配置，`__post_init__`会自动将这些散列字段合并为`LinkPreviewOptions`对象
`show_caption_above_media`	媒体消息的说明文字是否显示在媒体上方

ParseMode枚举定义于 aiogram/enums/parse_mode.py。

（2）start_polling轮询启动器

await dp.start_polling(bot)是长轮询入口。从 aiogram/dispatcher/dispatcher.py 的签名可见其丰富可调参数：

polling_timeout: int = 10：长轮询单次等待超时（秒）；
handle_as_tasks: bool = True：每个事件独立创建asyncio.Task并发处理；
backoff_config：指数退避重试配置（默认DEFAULT_BACKOFF_CONFIG）；
allowed_updates：接收哪些更新类型，默认UNSET时由resolve_used_update_types()根据已注册 handlers 自动解析（aiogram/dispatcher/dispatcher.py）；
handle_signals: bool = True：自动注册SIGINT/SIGTERM信号处理器（Windows 平台不支持信号处理，源码中add_signal_handler的NotImplementedError被显式抑制，见 aiogram/dispatcher/dispatcher.py）；
close_bot_session: bool = True：停机时关闭 bot 会话；
tasks_concurrency_limit：并发处理 updates 的上限（仅handle_as_tasks=True时生效，None表示不限制）。

start_polling内部还会：用self._running_lock防止重复启动、启动前触发emit_startup（即 router 的 startup 事件钩子）、随后为每一个传入的 bot 创建一个_polling任务。因此该 API 天然支持多机器人同时轮询（start_polling(bot1, bot2, ...)）。

另外注意一个使用细节：源码规定 bot 实例必须以位置参数传入（aiogram/dispatcher/dispatcher.py），若以dp.start_polling(bot=bot)形式传bot关键字会抛出ValueError。

运行方式

BOT_TOKEN=你的机器人Token python examples/echo_bot.py

程序会打印INFO级别日志，启动后向你的机器人发送任意消息即可看到回声效果：发送/start会收到Hello, <b>姓名</b>（HTML 加粗渲染），发送其他消息则被原样拷贝返回。

不使用 Dispatcher 的用法：纯 API 调用

docs/index.rst引入的第二个示例是 examples/without_dispatcher.py，官方注释点明其用途：只与 Bot API 交互，而不处理任何事件。当你的程序只需要“发消息”而不需要接收/响应更新时，这种轻量模式最合适。

完整示例代码

import asyncio from argparse import ArgumentParser from aiogram import Bot from aiogram.client.default import DefaultBotProperties from aiogram.enums import ParseMode def create_parser() -> ArgumentParser: parser = ArgumentParser() parser.add_argument("--token", help="Telegram Bot API Token") parser.add_argument("--chat-id", type=int, help="Target chat id") parser.add_argument("--message", "-m", help="Message text to sent", default="Hello, World!") return parser async def main() -> None: parser = create_parser() ns = parser.parse_args() token = ns.token chat_id = ns.chat_id message = ns.message async with Bot( token=token, default=DefaultBotProperties( parse_mode=ParseMode.HTML, ), ) as bot: await bot.send_message(chat_id=chat_id, text=message) if __name__ == "__main__": asyncio.run(main())

核心要点

（1）无需 Dispatcher，仅用 Bot

这个示例只导入Bot，完全绕开了Dispatcher的事件路由体系。因为没有事件需要分发，也就不存在 handler、过滤器与轮询任务。

（2）async with上下文管理器管理会话生命周期

async with Bot(token=token, default=DefaultBotProperties(parse_mode=ParseMode.HTML)) as bot: await bot.send_message(chat_id=chat_id, text=message)

Bot实现了异步上下文管理器协议（aiogram/client/bot.py）：进入async with时返回自身，退出时调用await self.session.close()关闭底层AiohttpSession。这意味着 HTTP 会话会被自动、干净地释放，避免资源泄漏。

（3）直接调用 API 方法

await bot.send_message(chat_id=chat_id, text=message)直接调用Bot实例上的send_message方法（定义于 aiogram/client/bot.py）。这里必须手动传入chat_id，因为没有事件上下文可以自动填充。这正是与上文message.answer()别名的主要区别：别名方法自动填参，直接方法需显式传参。

运行方式

python examples/without_dispatcher.py \ --token 你的机器人Token \ --chat-id 你的用户ID \ --message "Hello, aiogram!" # 不带 --message 时使用默认文本 "Hello, World!"

该示例适合的典型场景：定时任务推送、CI 构建通知、监控告警等“只发不收”的自动化脚本。注意它使用的是单次调用即退出的模式，与长驻轮询的 echo_bot 形成鲜明对比。

两种模式对比与选型建议

维度	echo_bot（Dispatcher 模式）	without_dispatcher（纯 Bot 模式）
导入对象	`Bot`+`Dispatcher`+ 过滤器/类型	仅`Bot`
事件处理	通过`@dp.message()`等装饰器注册 handler	不处理事件
启动方式	`dp.start_polling(bot)`长轮询常驻	`async with Bot(...)`单次执行即退出
传参方式	`message.answer()`自动填充`chat_id`	`bot.send_message()`手动传`chat_id`
典型场景	交互式聊天机器人	定时/告警推送脚本
会话管理	由`start_polling`的`close_bot_session`参数控制	`async with`自动关闭

选型建议：需要接收并响应用户消息时使用 Dispatcher 模式；只需主动发送消息时使用纯 Bot 模式，代码更精简且不引入额外开销。

更进一步：文档导航与生态

官方文档首页末尾通过toctree组织了完整的文档体系（docs/index.rst），可作为后续深入学习的路线图：

安装指南：PyPI / Arch / 开发版安装；
2.x 到 3.x 迁移指南：老版本用户升级必读；
API 参考：全部 types / methods / enums 的完整文档；
Dispatcher 指南：Router、FSM、中间件、过滤器等事件分发核心机制；
工具模块：格式化、deep linking 等辅助工具；
更新日志与贡献指南。

仓库中还包含大量可直接运行的示例，如 examples/finite_state_machine.py（FSM 状态机）、examples/echo_bot_webhook.py（Webhook 模式）、examples/error_handling.py（错误处理）等，均可在 examples 目录下找到。

小结

本文以官方文档首页收录的两个官方示例为骨架，完整还原了 aiogram 的两种典型用法：Dispatcher 驱动的轮询事件处理与纯 Bot 的轻量 API 调用，并从 aiogram/client/bot.py、aiogram/dispatcher/dispatcher.py、aiogram/client/default.py、aiogram/types/message.py 等源码层面揭示了start_polling参数、DefaultBotProperties默认属性传播、answer/send_copy快捷别名、async with会话管理等底层机制。掌握这两条路径后，你就已经具备构建生产级 Telegram Bot 的坚实基础。