Telegraf.js场景突然失效，报错：Cannot read properties of undefined (reading 'enter')

问题描述 #

昨日Telegraf.js场景功能运行正常，今日突然失效，报错信息：Cannot read properties of undefined (reading 'enter')，场景功能仿佛被框架移除。代码实现如下：

const nameScene = new Scenes.BaseScene('name');
nameScene.enter((ctx) => {
    ctx.reply('Please enter your name:');
});

nameScene.on('text', (ctx) => {
    if (!ctx.message.text) {
        ctx.reply('The name is required!');
        return;
    }

    ctx.session.name = ctx.message.text;
    ctx.scene.enter('surname');

});
// Scene 'surname'
const surnameScene = new Scenes.BaseScene('surname');
surnameScene.enter((ctx) => ctx.reply('Enter your last name:'));
surnameScene.on('text', (ctx) => {
    ctx.session.surname = ctx.message.text;
    ctx.scene.enter('city');
});

const cityScene = new Scenes.BaseScene('city');

const Stage = new Scenes.Stage([
    nameScene,
    surnameScene,
    cityScene,
]);
bot.use(Stage.middleware());
return Stage;


bot.action('fill_form', async (ctx) => {
    await ctx.answerCbQuery();
    await ctx.scene.enter('name');
});

问题原因及解决方案 #

1. 代码顺序错误：return Stage阻断后续代码执行 #

你在调用bot.use(Stage.middleware())后立刻执行return Stage，会直接跳出当前代码块，导致后续的bot.action('fill_form', ...)完全未被注册。若这段代码在函数内部，return还会中断bot实例的配置流程，使得Stage中间件无法正常向ctx注入scene对象，最终触发undefined报错。

解决：移除多余的return Stage语句，确保所有bot配置代码正常执行：

const Stage = new Scenes.Stage([
    nameScene,
    surnameScene,
    cityScene,
]);
bot.use(Stage.middleware());
// 移除 return Stage;

bot.action('fill_form', async (ctx) => {
    await ctx.answerCbQuery();
    await ctx.scene.enter('name');
});

2. 会话中间件缺失（隐性问题） #

Telegraf的Scene功能依赖session中间件维持状态，若bot未配置session中间件，也会导致ctx.scene无法初始化。检查bot是否添加了session配置，且要在Stage中间件之前注册：

const { Telegraf, Scenes, session } = require('telegraf');
const bot = new Telegraf('YOUR_BOT_TOKEN');

// 必须先注册session中间件
bot.use(session());
bot.use(Stage.middleware());

3. 依赖版本变更（可能性较低） #

若近期更新了Telegraf包，可能存在版本兼容性问题。可回退到之前正常运行的版本，或检查官方文档确认Scene API是否有变更：

npm install telegraf@<之前的版本号>

验证步骤 #

1. 移除return Stage语句，重启bot
2. 确认session中间件已正确注册在Stage中间件之前
3. 测试fill_form按钮触发场景的流程

内容的提问来源于stack exchange，提问作者Vadim Yanyushkin