从0到1开发你的第一个 Telegram 小程序外卖App

本文将基于一个真实的食品外卖 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 生态应用吧!