對於想進入 Telegram 生態的開發者來說，Telegram 小程式 (Mini App) 無疑是個絕佳的切入點。它不僅能觸及海量用戶，還能與支付、機器人等功能深度整合。但許多人一開始就卡在：到底該用什麼技術棧？如何配置開發環境？怎樣才能讓本地專案真正運行在 Telegram 裡？
本文將基於一個真實的食品外送 App 案例（類似 Durer King），帶你完成從 0 到 1 的開發流程。無論你是前端開發者，還是想嘗試 Telegram 生態的產品經理，這篇文章都能幫你快速上手。
Telegram 不僅是一款即時通訊工具，它的開放生態為開發者提供了極大的想像空間：
以本文的案例為例，我們將建構一個包含 Web App + Telegram Bot + 支付功能 的完整食品外送系統。前端使用 React.js，後端用 Node.js，並整合 Telegram 官方的支付能力。
在正式開始前，我們需要明確技術方案：
值得注意的是，Telegram 小程式強制使用 HTTPS 協議，這意味著本地開發時也需要配置 SSL 憑證。後續我們會詳細說明如何解決這個問題。
所有 Telegram 小程式都需要透過 Bot 來啟動。我們先透過 BotFather 創建一個機器人：
@BotFather 並打開對話/newbot 指令這個 Token 就像鑰匙，用於連接你的應用與 Telegram 伺服器。
接著我們使用官方的 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？有兩種解決方案：
修改 package.json 的啟動腳本：
"scripts": {
"start": "HTTPS=true react-scripts start"
}
這樣專案就會自動使用自簽名憑證運行在 https://localhost:3000。
如果你需要遠端測試（例如在手機上），可以使用 ngrok 將本地服務映射到公網：
ngrok http 3000
ngrok 會生成一個公網 HTTPS 位址，複製後即可在 Telegram 中使用。
現在我們要告知 Telegram，這個 Bot 的小程式入口在哪裡。回到 BotFather：
/mybots 選擇你剛創建的 BotBot Settings → Menu Buttonhttps://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 小程式框架。接下來可以：
如果你在多帳號管理、自動化測試等場景中需要防關聯瀏覽器，可以考慮使用 MasLogin。它能幫助你在開發測試階段模擬不同環境，避免帳號風險。
如果你使用免費版 ngrok，每次重啟後位址會變化。建議：
常用 API 包括：
window.Telegram.WebApp.ready() - 初始化window.Telegram.WebApp.MainButton - 主按鈕控制window.Telegram.WebApp.initData - 獲取用戶資訊window.Telegram.WebApp.close() - 關閉小程式詳細文件請參考 Telegram WebApp API。
Telegram 提供了沙盒環境，你可以使用測試支付憑證進行調試，具體流程請見 官方支付文件。
透過本文，你已經掌握了 Telegram 小程式的核心開發流程。記住：先跑通最小可用版本，再逐步迭代優化。現在就動手試試，打造屬於你的 Telegram 生態應用吧！
大綱
 (1) (1).png)
