用一个 Next.js 项目同时玩转 Telegram Bot 与 Mini App

本文将为你展示一种全新的开发思路：用一个 Next.js 5 项目同时实现 Telegram Bot 和 Mini App，真正做到一套代码、一次部署、无缝集成。你将学会如何搭建一个完整的积分游戏系统，包含每日签到奖励、Telegram Stars 真实支付和实时通知功能。

为什么选择 Next.js 统一开发 Bot 和 Mini App？

传统模式下，开发者需要：

• 单独部署 Bot 后端服务
• 单独部署 Mini App 前端应用
• 在两个项目之间做数据对接
• 维护两套环境变量和配置

而使用 Next.js 一体化方案，你可以：

• 一个代码库管理所有功能
• 共享 API 路由处理 Bot 指令、Mini App 请求和支付逻辑
• 统一部署到 Vercel 等平台，降低运维成本
• 数据天然打通，无需额外同步机制

这种方式特别适合快速验证想法、开发 MVP 产品或独立开发者快速上线项目。

---

核心功能演示：这个项目能做什么？

我们将构建一个积分游戏系统，具备以下功能：

• 每日签到奖励：用户每 24 小时可领取 100 积分，带实时倒计时显示
• Telegram Stars 支付：用户通过真实货币购买积分，支持即时退款测试
• Bot 指令处理：支持 /start、/help 等常用命令，一键启动 Mini App
• 实时通知推送：支付成功、退款完成等操作都会通过 Bot 发送消息提醒

整个系统运行在一个 Next.js 应用中，Bot 和 Mini App 的交互完全无缝。

---

开始前的准备工作

在正式开发前，你需要准备以下工具：

1. Telegram 账户：用于创建 Bot 和测试 Mini App
2. Node.js 18+：如果未安装，访问 nodejs.org 下载
3. Ngrok：用于本地开发时创建 HTTPS 隧道，因为 Telegram 要求 Webhook 和 Mini App 必须使用 HTTPS

如何获取 Ngrok

• 访问 ngrok.com 注册免费账户
• 下载对应操作系统的版本
• 解压到专用文件夹
• 运行 ngrok config add-authtoken <你的token> 绑定账户
• 完成后可以随时在该文件夹运行 ngrok http 3000

---

快速搭建项目（5 分钟上手）

1. 获取项目代码并安装依赖

你可以从相关 Telegram 频道获取完整源码和详细文档（具体链接可在原视频描述中找到）。

git clone <项目仓库地址>
cd <项目目录>
npm install

2. 配置环境变量

在项目根目录创建 .env.local 文件，用于存储敏感信息：

TELEGRAM_BOT_TOKEN=你的Bot令牌
NEXT_PUBLIC_APP_URL=你的Ngrok地址

重要提示：确保 .env.local 已加入 .gitignore，避免泄露 Bot Token。

3. 创建 Telegram Bot

• 打开 Telegram，搜索 BotFather
• 发送 /newbot 创建新 Bot
• 设置 Bot 名称和用户名（必须以 bot 结尾）
• 复制生成的 Bot Token 并保存到 .env.local

4. 启动 Ngrok 和开发服务器

# 终端 1：启动 Ngrok
ngrok http 3000

# 终端 2：启动 Next.js 开发服务器
npm run dev

# 终端 3：设置 Webhook
npm run webhook:setup

如果一切正常，你会看到 "Webhook set successfully" 的提示。

5. 配置 Mini App 菜单按钮

• 回到 BotFather，发送 /mybots 选择你的 Bot
• 点击 Bot Settings → Menu Button
• 填写 URL（使用 Ngrok 提供的 HTTPS 地址）和按钮文字（如"Play Game"）

现在，用户打开你的 Bot 时，会看到一个启动游戏的按钮，点击即可进入 Mini App 界面！

---

核心代码解析：Bot 和 Mini App 如何协同工作？

Webhook 端点：Bot 的消息中枢

所有 Telegram 发送的更新（用户指令、支付回调等）都会通过 Webhook 传递到 /api/telegram/webhook 路由。

主要处理的消息类型包括：

• 用户指令：/start、/help 等
• 支付前确认：用户点击支付按钮后的预检查
• 支付成功回调：确认交易完成并发放积分
• 退款请求：开发阶段可快速测试退款流程

当用户首次发送 /start 时，Bot 会立即推送一个「启动游戏」按钮，无需额外引导。

Telegram Stars 支付流程

支付功能的核心在于 /api/buy-points 路由：

1. 用户在 Mini App 点击「购买积分」
2. 调用 Telegram Bot API 创建发票（createInvoiceLink）
3. 发票在 Telegram 原生支付界面展示
4. 用户完成支付后，Webhook 接收通知
5. 系统更新用户积分并发送收据消息

关键配置：

• provider_token 留空（Telegram Stars 模式）
• currency 设为 XTR
• prices 单位为星星数量（非分）

开发者福利：每次购买后会返回收据 ID，你可以立即用 /refund <收据ID> 测试退款，无需等待审核或人工处理。这对于测试真实支付流程极为高效。

每日签到奖励系统

在 /api/claim-daily 路由中，我们实现了基于时间的激励机制：

• 记录每个用户的上次领取时间
• 检查是否已过 24 小时
• 如未满 24 小时，返回倒计时剩余时间
• 领取成功后发放 100 积分并推送 Telegram 通知

前端使用 实时倒计时组件，每秒更新剩余时间，让用户清楚知道何时可以再次领取。这种模式可以扩展到任何需要时间限制的游戏玩法（如能量恢复、抽奖冷却等）。

---

生产环境部署注意事项

虽然本文使用内存存储进行演示，但真实项目上线前必须做以下改造：

• 数据库：用 PostgreSQL 或 MongoDB 替代内存存储
• 用户验证：验证 Telegram Web App 数据签名，防止伪造请求
• 限流保护：避免恶意刷取积分或滥用支付接口
• 日志监控：接入错误追踪服务（如 Sentry）
• Webhook 安全：验证请求来源确实是 Telegram 服务器

部署平台推荐：

• Vercel：零配置部署，自动 HTTPS
• Heroku / Railway：适合需要长连接的场景
• Cloudflare Workers：边缘计算方案，全球加速

部署时记得更新 Webhook URL 和 Mini App 菜单链接 为生产域名。

---

常见问题（FAQ）

为什么需要 Ngrok？直接用 localhost 不行吗？

Telegram 的 Webhook 和 Mini App 都要求使用 HTTPS 协议，localhost 无法满足这一要求。Ngrok 可以创建一个公网可访问的 HTTPS 隧道，将请求转发到你的本地开发服务器。

如何测试真实支付但不花钱？

在开发阶段，你可以购买少量 Telegram Stars（最低几毛钱），然后使用 /refund 指令立即退款。这样可以用真实流程测试支付、Webhook 回调和退款逻辑，无需反复充值。

生产环境可以继续用内存存储吗？

绝对不行。内存存储在服务器重启后会丢失所有数据。必须使用持久化数据库（如 PostgreSQL），并做好备份和迁移方案。

Next.js 一体化方案的主要优势是什么？

最大优势是开发效率和维护成本的降低。你不需要：

• 管理两套代码仓库
• 担心前后端数据不一致
• 配置复杂的跨域和 API 对接
• 分别部署和监控两个服务

所有逻辑都在一个项目中，代码复用率高，Bug 定位更快。

这种架构适合大规模应用吗？

对于 MVP 产品和中小型应用完全够用。如果日活用户达到百万级别，建议将 Bot 后端和 Mini App 前端拆分，使用微服务架构和专门的消息队列处理高并发。

---

总结

通过本文的实战演示，你已经掌握了用 Next.js 构建 Telegram Bot + Mini App 一体化应用的核心技能。这种开发模式可以帮助你快速验证想法、降低开发成本，并为后续扩展打下坚实基础。立即动手尝试，用最短时间打造属于自己的 Telegram 小游戏吧！