從零開發 Telegram 小程式：食品外送實戰教學

本文將基於一個真實的食品外送 App 案例（類似 Durer King），帶你完成從 0 到 1 的開發流程。無論你是前端開發者，還是想嘗試 Telegram 生態的產品經理，這篇文章都能幫你快速上手。

---

為什麼選擇 Telegram 小程式？

Telegram 不僅是一款即時通訊工具，它的開放生態為開發者提供了極大的想像空間：

• 原生支付整合：無需對接第三方，直接使用 Telegram Payments 完成交易閉環。
• 用戶觸及成本低：用戶無需下載額外 App，直接在聊天介面打開即可使用。
• 跨平台體驗統一：無論是 Web 版、行動端還是桌面端，用戶體驗高度一致。

以本文的案例為例，我們將建構一個包含 Web App + Telegram Bot + 支付功能 的完整食品外送系統。前端使用 React.js，後端用 Node.js，並整合 Telegram 官方的支付能力。

---

技術選型與開發準備

在正式開始前，我們需要明確技術方案：

• 前端框架：React.js + TypeScript（類型安全，適合中大型專案）
• 後端服務：Node.js（與 Telegram API 無縫對接）
• 開發工具：Telegram Mini App SDK（官方推薦，功能豐富）
• 環境要求：HTTPS 協議（Telegram 強制要求）

值得注意的是，Telegram 小程式強制使用 HTTPS 協議，這意味著本地開發時也需要配置 SSL 憑證。後續我們會詳細說明如何解決這個問題。

---

第一步：創建 Telegram Bot

所有 Telegram 小程式都需要透過 Bot 來啟動。我們先透過 BotFather 創建一個機器人：

1. 在 Telegram 中搜尋 @BotFather 並打開對話
2. 發送 /newbot 指令
3. 依照提示輸入 Bot 名稱和使用者名稱
4. 創建成功後，你會收到一個 API Token（務必保存好，後續會用到）

這個 Token 就像鑰匙，用於連接你的應用與 Telegram 伺服器。

---

第二步：初始化專案與安裝 SDK

接著我們使用官方的 Telegram Mini App SDK 快速搭建專案：

# 創建 React + TypeScript 專案
npx create-react-app my-telegram-app --template typescript
cd my-telegram-app

# 安裝 Telegram SDK
npm install @twa-dev/sdk

SDK 提供了豐富的 API，例如獲取用戶資訊、呼叫支付介面、傳送訊息等。安裝完成後，用 VS Code 打開專案並啟動：

npm start

此時你會看到專案運行在 http://localhost:3000，但這還不夠——Telegram 要求所有小程式必須透過 HTTPS 訪問。

---

第三步：配置 HTTPS 環境

許多開發者在此步驟卡關：本地開發時怎麼用 HTTPS？有兩種解決方案：

方案 1：使用本地 SSL 憑證

修改 package.json 的啟動腳本：

"scripts": {
  "start": "HTTPS=true react-scripts start"
}

這樣專案就會自動使用自簽名憑證運行在 https://localhost:3000。

方案 2：使用 ngrok（推薦）

如果你需要遠端測試（例如在手機上），可以使用 ngrok 將本地服務映射到公網：

ngrok http 3000

ngrok 會生成一個公網 HTTPS 位址，複製後即可在 Telegram 中使用。

---

第四步：將 Web App 掛載到 Bot

現在我們要告知 Telegram，這個 Bot 的小程式入口在哪裡。回到 BotFather：

1. 發送 /mybots 選擇你剛創建的 Bot
2. 點擊 Bot Settings → Menu Button
3. 輸入剛才的 HTTPS 位址（例如 https://your-ngrok-url.io）

完成後，打開你的 Bot，點擊底部的 Menu 按鈕，小程式就會在 Telegram 內打開！

---

第五步：初始化程式碼與測試

清理 React 預設程式碼，保留核心結構：

import { useEffect } from 'react';
import './App.css';

function App() {
  useEffect(() => {
    // 初始化 Telegram SDK
    const tg = (window as any).Telegram.WebApp;
    tg.ready();
    console.log('Telegram WebApp 已載入');
  }, []);

  return (
    <div className="App">
      <h1>Hello Telegram!</h1>
    </div>
  );
}

export default App;

保存後刷新 Telegram，你應該能看到 "Hello Telegram!" 的頁面，同時在控制台看到 SDK 初始化成功的日誌。

---

第六步：樣式規範與全域配置

為了保證在不同裝置上的顯示一致性，建議使用 Normalize.css 並設定全域樣式：

/* App.css */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  background-color: var(--tg-theme-bg-color);
  color: var(--tg-theme-text-color);
}

Telegram 提供了一套 主題變數，使用這些變數能讓你的 App 自動適配用戶的深色/淺色模式。

---

後續開發方向

完成以上步驟後，你已經擁有了一個可運行的 Telegram 小程式框架。接下來可以：

• 添加頁面路由：使用 React Router 實現多頁面跳轉
• 整合後端 API：透過 Node.js 搭建訂單管理、商品列表等介面
• 接入支付功能：呼叫 Telegram Payments API 完成交易
• 優化用戶體驗：添加載入動畫、錯誤提示、購物車邏輯等

如果你在多帳號管理、自動化測試等場景中需要防關聯瀏覽器，可以考慮使用 MasLogin。它能幫助你在開發測試階段模擬不同環境，避免帳號風險。

---

常見問題（FAQ）

為什麼我的小程式在 Telegram 中無法打開？

• 檢查是否使用了 HTTPS 協議（HTTP 會被攔截）
• 確認 Bot 的 Menu Button 位址設定正確
• 查看瀏覽器控制台是否有錯誤提示

本地開發時，每次修改都要重新配置 ngrok 嗎？

如果你使用免費版 ngrok，每次重啟後位址會變化。建議：

• 升級到 ngrok 付費版（可固定網域）
• 或使用 Cloudflare Tunnel 等替代方案

Telegram SDK 支援哪些功能？

常用 API 包括：

• window.Telegram.WebApp.ready() - 初始化
• window.Telegram.WebApp.MainButton - 主按鈕控制
• window.Telegram.WebApp.initData - 獲取用戶資訊
• window.Telegram.WebApp.close() - 關閉小程式

詳細文件請參考 Telegram WebApp API。

如何在 Telegram 中測試支付功能?

Telegram 提供了沙盒環境，你可以使用測試支付憑證進行調試，具體流程請見 官方支付文件。

---

總結

透過本文，你已經掌握了 Telegram 小程式的核心開發流程。記住：先跑通最小可用版本，再逐步迭代優化。現在就動手試試，打造屬於你的 Telegram 生態應用吧！