
在 aiogram 3.x 中,FSM 上下文(FSMContext)需通过函数参数自动注入,但参数名必须严格为 state(全小写),若误用 State、context 等其他名称将导致 TypeError。
在 aiogram 3.x 中,fsm 上下文(fsmcontext)需通过函数参数自动注入,但参数名必须严格为 `state`(全小写),若误用 `state`、`context` 等其他名称将导致 typeerror。
在使用 aiogram 的有限状态机(FSM)功能时,开发者常期望像文档示例一样,直接在处理器函数中声明 FSMContext 类型的参数并接收上下文实例。然而,该机制并非基于类型注解自动推导,而是依赖参数名称的约定式注入——aiogram 内部的 FSM 中间件会主动查找名为 state(全小写)的参数,并将 FSMContext 实例注入其中。
例如,以下写法是错误的(即使类型注解正确):
async def start(
message: Message | CallbackQuery,
State: FSMContext # ❌ 错误:参数名首字母大写
):
await state.set_state(MyStates.waiting_for_input) # 此处 state 未定义!这会导致运行时报错:TypeError: start() missing 1 required positional argument: 'State',因为 aiogram 并不识别 State 这个参数名,无法完成自动注入。
✅ 正确写法如下(参数名必须为 state):
from aiogram.fsm.context import FSMContext
from aiogram.types import Message, CallbackQuery
@Router.message(CommandStart())
@Router.callback_query(F.data == "start")
async def start(
message_or_callback: Message | CallbackQuery,
state: FSMContext # ✅ 必须为全小写 'state'
):
# 清除可能残留的状态
await state.clear()
# 设置新状态(如已定义 MyStates)
# await state.set_state(MyStates.main_menu)
print("/Started")
# 根据消息或回调对象统一响应
if isinstance(message_or_callback, Message):
await message_or_callback.answer("欢迎使用!")
else:
await message_or_callback.answer("已返回主菜单")
await message_or_callback.message.edit_text("欢迎使用!")⚠️ 注意事项:
-
state是强制约定名,不可替换为ctx、fsm_context、State或其他任何形式; - 类型注解
FSMContext可选(用于 IDE 提示和静态检查),但不参与注入逻辑; - 若同时需要
Bot、Session、State等多个上下文对象,均需遵循各自命名规范(如bot: Bot,session: AsyncSession,state: FSMContext); - 确保已正确配置
Dispatcher的storage(如RedisStorage),否则state注入虽成功,但状态数据无法持久化。
总结:aiogram 3.x 的 FSMContext 注入是“名称驱动”而非“类型驱动”。牢记 state 这一魔法参数名,是避免 missing 1 required positional argument 错误的关键。

















