如何打造你的第一个 Telegram Mini App：分步指南

Telegram vs. WeChat：超级应用之战

多年来，WeChat 一直稳居超级应用之首。它于 2011 年上线，将即时通讯、社交媒体、支付和电商无缝整合到一个平台中，很快成为中国人日常生活中不可或缺的一部分。Telegram 虽然到 2013 年才推出，却迅速迎头赶上，成为全球超级应用领域的一股强劲力量。如今，开发者可以直接在 Telegram 环境中打造创新服务，甚至构建 Telegram 小型解决方案。借助完善的 Mini App 文档，无论是想创建 Telegram 机器人，还是用熟悉的 Web 技术开发 Telegram Mini App，都能比以往更轻松地上手。

Telegram 和 WeChat 的主要区别：

WeChat 长期凭借一站式应用的优势称霸中国市场，而 Telegram 正在全球舞台上发力，向它发起有力挑战。凭借对隐私的重视、前沿功能和开发者工具，Telegram 正在开辟一片独特天地。得益于 Telegram Mini Apps，开发者如今可以创建与平台无缝集成的 Web 应用，帮助 Telegram 快速缩小差距，并吸引全球更多用户。

接下来，我们来看看如何创建 Telegram Mini App，加入这股不断壮大的开发者浪潮，充分释放 Telegram 的潜力。

什么是 Telegram Mini Apps？它们为何如此受欢迎？

Telegram Mini Apps 本质上是在 Telegram 平台内运行的 Web 应用。你可以把它们看作是用 HTML、CSS 和 JavaScript 构建的普通网站，只不过还能通过 SDK 使用 Telegram 的独特功能。这些应用可直接在 Telegram 中启动，为用户带来流畅的体验、数据集成和内置支付功能。要充分利用 Telegram 开发 Mini Apps，开发者通常会先通过 BotFather 创建 Telegram 机器人，为它设置用户名，再配置相关选项，将机器人与应用连接起来。设置完成后，就可以在 Telegram 群组中分享 Mini Apps，也可以直接发送给用户，让它们成为生态系统的强大延伸。对于希望充分利用这一平台的开发者来说，了解 Telegram Mini Apps 的工作原理至关重要。

开发者为何青睐 TMA：

成功的 Telegram Mini Apps 示例

来看看几个真实案例，了解 Telegram Mini Apps 能实现什么：

• Wallet – 通过 Telegram 使用钱包服务的案例；具体功能取决于所用钱包和所在地区。
• Hamster Kombat – 一款获得大量用户参与的点击类游戏。
• DurgerKing – Telegram 提供的示例 Mini App，可用于体验点餐和支付流程。

如何开始使用 Telegram Mini Apps

你需要准备：

• 代码编辑器（VS Code 或 WebStorm 都可以）。
• HTML、CSS 和 JavaScript 基础知识。
• 手机和电脑上都安装了 Telegram。
• 愿意探索新事物。

第 1 步：创建辅助机器人

先创建一个 Telegram 机器人，作为应用的入口。操作方法如下：

1. 在 Telegram 中搜索 @BotFather。
2. 发送命令 /newbot。
3. 为机器人取个名字。
4. 妥善保管 BotFather 提供的 token，并将其存放在服务器上——调用 Bot API 时会用到。切勿将 token 放进浏览器代码或公开代码库。

下面是适用于服务器的 Node.js 代码。安装 node-telegram-bot-api，通过服务器端环境变量设置 token，并在运行前将 https://your-domain.com/app 替换为部署后的 HTTPS URL。下面的 web_app 内联按钮适用于与机器人的私聊：

javascript
const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot(token, { polling: true });

bot.onText(/\/start/, (msg) => {
const chatId = msg.chat.id;
bot.sendMessage(chatId, 'Welcome! Click the button below to open the app.', {
reply_markup: {
inline_keyboard: [[
{
text: 'Open App',
web_app: { url: 'https://your-domain.com/app' }
}
]]
}
});
});

第 2 步：搭建开发环境

先搭建基本的项目结构，为开发 Telegram Mini App 做好准备，并配置测试环境：

项目目录结构（index.html 的内容见第 3 步）：

text
my-tma/
├── index.html
├── styles/
│ └── main.css
├── scripts/
│ └── app.js
└── assets/
└── images/

第 3 步：构建应用

将以下 HTML 保存为 index.html。它会加载 Telegram WebApp bridge 和 scripts/app.js。这只是 UI 示例，并未实现身份验证：在信任用户身份之前，请先在后端验证 Telegram initData。
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My First TMA</title>
<link rel="stylesheet" href="styles/main.css">
<script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
<div id="app">
<h1>你好，Telegram！</h1>
</div>
<script src="scripts/app.js"></script>
</body>
</html>

为应用设置样式

请将下面的 JavaScript 代码保存为 scripts/app.js。setupTheme 会应用 Telegram 的主题颜色；styles/main.css 则是单独的样式表，你可以按需自定义。请分别在 Android 和 iOS 版 Telegram 中测试。注意：sendData 仅适用于通过回复键盘上的 web_app 按钮启动的 Mini Apps，不适用于第 1 步中的内联按钮。如果要保存通过内联按钮启动的应用数据，请实现一个后端接口并验证 initData；此示例不会持久化数据，也不会处理传入的 web_app_data 消息：

javascript
const app = {
data: { count: 0 },

init() {
this.setupTheme();
this.setupCounter();
this.setupMainButton();
},

setupTheme() {
const theme = window.Telegram.WebApp.themeParams;
document.body.style.backgroundColor = theme.bg_color;
document.body.style.color = theme.text_color;
},

setupCounter() {
const counter = document.createElement('div');
counter.innerHTML = `
<h2>计数器：<span id="count">0</span></h2>
<button id="increment">+1</button>
<button id="decrement">-1</button>
`;
document.querySelector('#app').appendChild(counter);

document.querySelector('#increment').onclick = () => this.updateCount(1);
document.querySelector('#decrement').onclick = () => this.updateCount(-1);
},

setupMainButton() {
const MainButton = window.Telegram.WebApp.MainButton;
MainButton.setText('保存');
MainButton.onClick(() => this.saveData());
MainButton.show();
},

updateCount(delta) {
this.data.count += delta;
document.querySelector('#count').textContent = this.data.count;
},

saveData() {
window.Telegram.WebApp.sendData(JSON.stringify(this.data));
}
};

window.Telegram.WebApp.ready();
app.init();

扩展功能

完成基础搭建后，你可以通过以下高级功能进一步完善 Mini App：

• 按需添加基于 TON 的 Web3 功能；但在 Telegram 内购买数字商品和服务时，必须使用 Telegram Stars，不能使用 TON。
• 为数字商品和服务接入 Telegram Stars 支付，并妥善处理付款确认和退款。
• 验证 initData 并检查所有提交的值后，将用户数据保存到服务器。
• 添加动画和高级逻辑。
• 在获得用户必要授权后发送机器人通知；Mini App 不能随意向用户发送消息。
• 添加菜单按钮，方便用户导航。

接下来做什么？

1. 将应用部署到支持 HTTPS 的服务器上。
2. 通过 @BotFather 将应用接入 Telegram。
3. 在真实环境中调试和测试。
4. 发布你的 Telegram Mini App，收集第一批用户反馈。
5. 将代码分享到 GitHub，听取社区反馈；不要上传机器人令牌、密钥或个人数据。
6. 收集用户反馈并持续改进。

按照这些步骤，你就能稳步打造出成功的 Telegram Mini App，充分利用 Telegram 不断壮大的生态系统。