用一個 Next.js 專案搞掂 Telegram Bot 同 Mini App

本文將為你展示一種全新的開發思路：用一個 Next.js 專案同時實現 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 小遊戲吧！