使用Telegraf Stage与TypeScript时类型定义报错求助

问题根源 #

你的类型定义错误在于自定义上下文与Telegraf Scene所需的类型体系不兼容：

1. 手动扩展的Bot接口强制session为必填的BotSession，但Stage期望的上下文里session可能为undefined（会话中间件初始化前的状态），导致类型不匹配。
2. 上下文类型组合方式错误，没有正确使用Telegraf提供的SessionContext和SceneContext工具类型来整合自定义会话数据。

修正方案 #

1. 重新定义Bot上下文与会话类型（bot/index.ts） #

替换原有的类型定义，使用Telegraf官方提供的类型工具来组合上下文：

import { Telegraf, Context, Scenes, SessionContext } from 'telegraf';
import dotenv from 'dotenv';
import LocalSession from 'telegraf-session-local';

const result = dotenv.config();
if (result.error || !result.parsed) {
  throw result.error || new Error('No data loaded from env');
}

// 自定义会话数据
export interface SessionData {
  lastRequest?: Date;
  menuMessage: number;
}

// 组合Telegraf场景会话数据与自定义会话数据
type BotSession = Scenes.SceneSession & SessionData;

// 正确组合基础上下文、会话上下文、场景上下文
type Bot = Context & SessionContext<BotSession> & Scenes.SceneContext;

const telegramKey: string = result.parsed['TELEGRAM_KEY'];
const bot = new Telegraf<Bot>(telegramKey);

// 初始化本地会话，设置默认值避免session为undefined
const session = new LocalSession<Bot>({
  property: 'session',
  defaultSession: () => ({
    menuMessage: 0 // 根据业务需求设置默认值
  })
});

bot.use(session.middleware());
// 注册Stage中间件（记得导入stage）
import stage from '../scenes/index.js';
bot.use(stage.middleware());

export default bot;
export type { Bot, BotSession };

2. 修正Stage的类型参数（scenes/index.ts） #

直接使用修正后的Bot类型即可：

import { Scenes } from 'telegraf';
import scanImage from './scanImage.js';
import { Bot } from '../bot/index.js';

// 现在类型匹配不会报错
const stage = new Scenes.Stage<Bot>([scanImage]);

export default stage;

3. 确保场景的类型一致性（scenes/scanImage.ts） #

场景定义也要使用Bot类型：

import { Scenes } from 'telegraf';
import { Bot } from '../bot/index.js';

const scanImage = new Scenes.BaseScene<Bot>('scan-image');

scanImage.enter((ctx) => {
  // ctx.session将自动拥有SessionData的类型提示
  return ctx.reply(`当前菜单消息ID：${ctx.session.menuMessage}`);
});

// 其他场景逻辑...

export default scanImage;

关键说明 #

• 使用SessionContext<BotSession>来关联会话数据，符合Telegraf的类型规范，避免手动扩展接口导致的冲突。
• 设置defaultSession确保会话始终有初始值，消除session为undefined的可能性，解决类型不兼容问题。
• 所有上下文相关的类型（Bot、场景、中间件）统一使用Bot类型，保证类型一致性。

内容的提问来源于stack exchange，提问作者La Ayze