如何构建 Telegram Mini App

Telegram Mini Apps 是一个强大的平台，可用于开发直接集成到 Telegram 中的 Web 应用。本指南将一步步介绍如何创建自己的 Mini App，从初始设置到部署，再到通过 AdsGram 变现。

什么是 Telegram Mini Apps？

Telegram Mini Apps 是在 Telegram 界面内运行的 Web 应用，无需从应用商店下载或另行安装，就能为用户提供互动体验。它们基于标准 Web 技术构建，可为开发者带来：

• 在 Telegram 全球生态中分发；但曝光并非自动获得
• 与 Telegram 界面和功能的原生集成
• 跨平台兼容（iOS、Android、桌面端和网页版）
• 通过机器人链接和菜单按钮轻松分发

应用开发流程

创建过程包括三个核心阶段：

1. 注册机器人和 Mini App：通过 BotFather 配置 Telegram 机器人和 Mini App
2. 开发应用：使用 React、Vue 或原生 JavaScript 构建；React 和 Vue 是可选的界面工具
3. 部署与集成：托管应用并将其接入 Telegram 生态

本文将逐步介绍每个阶段，包括开发最佳实践、测试策略，以及通过专注 Telegram Mini Apps 的广告平台 AdsGram 实现变现的机会。

开发环境设置

不要让未完成的改动影响真实用户。请使用独立的预发布环境，必要时使用 Telegram 测试环境。测试后端只是一种选择，并非界面开发每个阶段都必须使用。

了解 Telegram 测试环境

Telegram 提供专为开发和测试设计的独立测试环境。这一隔离环境与生产环境功能一致，并具备几项重要优势：支持 HTTP 协议（本地开发时无需 SSL 证书）、无需域名即可通过 IP 地址直接访问，并且与生产环境的机器人和真实用户数据完全隔离。

生产环境与测试环境对比

切换到测试环境

目前文档中记载的入口如下。Telegram Desktop：设置 → Shift + Alt + 右键点击“添加账号” → 测试服务器。iOS：点击“设置”图标 10 次 → 账号 → 登录其他账号 → 测试。macOS 原生客户端可通过调试菜单操作。菜单因客户端和版本而异，不要默认 Android 上也有相同的隐藏菜单。

请注意，测试账号与生产账号完全独立。你需要在测试环境中通过 BotFather 创建新的测试机器人。

开发流程

请在本地或独立的预发布环境中开发。Telegram 测试环境允许 Mini Apps 使用 HTTP，但设备仍需能够访问你的服务器；localhost 指的是设备本身。发布前，请测试生产环境的 HTTPS URL 和所有必要功能。AdsGram 集成是可选的，应单独测试。

这种隔离让开发过程更专业、安全和高效，你可以放心构建，而不必担心影响生产环境的稳定性。

开发前的准备

这一阶段决定了应用的便捷程度和实用价值。别担心，整个过程并不复杂，即使没有经验也能掌握。你将学会如何从零开始构建高效的 Mini App。

• 确定 Mini App 的目标

首先，想清楚为什么需要 Mini App。它可以是：

用于娱乐用户、提升参与度的游戏。实用工具（例如计算器、翻译工具或任务规划工具）。沟通服务（例如客服机器人或自动化常见问题解答）。

重要的是明确 Mini App 要解决什么问题。目标越清晰，就越容易设计它的结构和功能。

• 选择开发平台和技术

确定目标后，接下来就该选择用什么来开发应用了。以下是一些常见选择：

如果你了解编程基础，JavaScript 是绝佳选择。你可以用它创建在 Telegram 生态中流畅运行的 Web 应用。Telegram 对这项技术提供了很好的支持，也很适合快速上手。React。这是一个用于构建用户界面的库。它能简化组件创建和用户交互，非常适合开发 Mini App。其他 Web 技术。你也可以使用 HTML 和 CSS 创建应用界面。这些基础元素能让项目既美观又实用。

其他框架也可以使用，前提是它们生成的 Web 应用能在 Telegram 的 WebView 中运行，并支持所需的 Telegram 集成。

创建机器人并注册 Mini App

要创建 Telegram Mini App，首先需要通过 Telegram 官方机器人管理工具 BotFather 设置一个 Telegram 机器人。BotFather 是平台上所有机器人和 Mini Apps 的中央管理工具。

设置机器人

打开 Telegram 并搜索 @BotFather。开始对话并使用 /newbot 命令。BotFather 会引导你填写显示名称和唯一用户名（必须以“bot”结尾，例如 MyCoolMiniApp_bot）。

创建完成后，BotFather 会提供一个身份验证令牌。请将其安全地保存在环境变量中，因为它拥有机器人的完全控制权。

注册 Mini App

在 BotFather 中使用 /newapp 命令注册新的 Mini App，并将其关联到机器人。填写应用短名称、描述和图标。你的 Mini App 将获得一个直接链接： https://t.me/{bot_username}/{app_short_name}.

菜单按钮还是直接链接：选择集成方式

Telegram 提供两种访问 Mini App 的方式，分别适用于不同用途。

菜单按钮集成

用户与机器人互动时，菜单按钮会显示在聊天界面左下角。这种方式能让 Mini App 成为机器人功能的自然延伸。

设置： 向 BotFather 发送 /setmenubutton → 选择机器人 → 提供 Web 应用 URL（生产环境必须使用 HTTPS）→ 输入按钮标题。

适用于： 与机器人集成的应用、个性化仪表盘、客服工具，以及与机器人工作流相关的应用；但不会自动获得聊天记录访问权限。

直接链接集成

直接链接可创建独立的 Mini Apps，用户通过可分享的 URL 即可访问，无需先与机器人互动。非常适合受益于病毒式传播的独立应用。

设置： 向 BotFather 发送 /myapps → 选择 Mini App → 点击“Edit Web App URL”→ 输入 URL（生产环境必须使用 HTTPS）。

适用于： 独立游戏、电商店铺、实用工具、病毒式传播应用和营销驱动型应用。

如何选择

如果应用是对机器人命令的补充，请选择菜单按钮；它不会自动获得聊天记录访问权限。如果应用可独立运行并适合直接分享，请选择直接链接。你也可以同时使用两种方式：用菜单按钮服务机器人用户，用直接链接获取新用户并实现病毒式增长。

无论选择哪种方式，生产环境中的 URL 都必须使用带有效 SSL 的 HTTPS（HTTP 仅限测试环境）。两种配置都支持集成 AdsGram 进行变现。

开发 Mini App

开发 TMA 时，你可以使用 React 等不同框架，也可以用 Web 技术和 Telegram 服务从零开始创建应用。无论是简单的机器人还是复杂的互动应用，这份分步指南都能帮你完成整个过程。

这些 Web 应用直接在 Telegram 界面中运行，无需前往应用商店，就能为用户带来流畅的体验。

记住，这一切并没有看上去那么难。

第 1 步：创建项目

首先创建一个 Telegram Mini App 项目，它将成为 Mini App 的基础。你可以使用文本编辑器或开发环境（IDE），例如 VS Code、WebStorm，甚至 Sublime Text 这样的简单编辑器。它们有助于组织代码，让编写更方便。你还需要设置合适的测试环境，确保一切正常运行。

为项目创建一个文件夹，并在其中创建以下文件：

index.html：包含 Web 应用 HTML 代码的文件。style.css：包含界面样式（CSS）；在这个最简示例中可以留空。app.js：存放主要代码，用于控制应用逻辑以及与 Telegram 服务的交互。

第 2 步：编写代码

项目结构准备好后，就可以开始编写代码了。下面来看看如何设置应用并让它具备交互能力。你需要确保应用运行正常，并具备合适的调试手段。

连接 Telegram 服务

Telegraf 是用于服务器端机器人的 Node.js 库，不是浏览器 SDK。请仅将 BotFather 令牌保存在服务器端的 BOT_TOKEN 环境变量中，不要放入 index.html 或 app.js。Mini App 用户身份需要在服务器端单独校验 Telegram initData；Telegraf 不会自动完成这项工作。

使用以下命令安装 Telegraf：

bash
npm install telegraf

将这个服务器端示例保存为 bot.js，设置 BOT_TOKEN，然后运行 node bot.js：

javascript
const { Telegraf } = require('telegraf');
const bot = new Telegraf(process.env.BOT_TOKEN);

bot.start((ctx) => ctx.reply('Hello! This is your Mini App bot.'));
bot.launch();

当用户发送 /start 时，这个机器人会回复；它不会打开 Mini App，也不会在启动时向所有用户发送消息。请单独配置菜单按钮或直接链接。Web3 和钱包集成是可选的，本示例中未实现。

创建界面

创建一个包含 index.html、style.css 和 app.js 的 public 文件夹。将以下 HTML 保存为 public/index.html。这个最简界面还没有身份验证，也没有连接 Telegram：

html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="style.css">
<title>My Mini App</title>
</head>
<body>
<div id="app">
<button id="startBtn">Start game</button>
</div>
<script src="app.js"></script>
</body>
</html>

第 3 步：编写应用逻辑

客户端的 app.js 负责处理浏览器交互。下一个示例只会在点击按钮时显示提示；实际的游戏或服务逻辑需要另行添加。要使用 Telegram API，请加载 Telegram WebApp 脚本并使用其支持的方法。在信任用户身份之前，请先在后端校验 initData。

保持界面清晰易用。机器人发送消息需要用户此前有过互动或授予相应的发送权限；Mini App 不能随意发送后台通知。

第 4 步：启动和测试

将这个点击处理程序保存为 public/app.js，然后在浏览器和 Telegram 内测试按钮：

javascript
document.getElementById('startBtn').addEventListener('click', function() {
alert('The game has started!');
// Add code here to start your game or other application logic.
});

静态界面使用 Live Server 就足够了。使用 bot.launch() 的机器人需要长期运行的 Node.js 进程；不要将这种轮询进程原样部署为短时运行的无服务器函数。界面请使用支持 HTTPS 的预发布托管，机器人则使用合适的进程或 webhook 部署。

如果使用可长期运行 Node.js 的托管服务，请通过 npm install express 安装 Express，并将以下内容保存为 public/ 旁边的 server.js。设置 BOT_TOKEN，然后运行 node server.js 代替 bot.js；不要用同一个令牌同时运行两者。这个示例增加了静态文件服务，并从环境中读取令牌。请在托管层配置 HTTPS：

javascript
const express = require('express');
const { Telegraf } = require('telegraf');
const path = require('node:path');
const app = express();
const bot = new Telegraf(process.env.BOT_TOKEN);

// Serve only the client files in the public directory.
app.use(express.static(path.join(__dirname, 'public')));

// Bot logic
bot.start((ctx) => ctx.reply('Hello! The bot is running on the server.'));
bot.launch();

// Port configuration
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(Server running on port ${PORT});
});

现在你有了基础界面和机器人/服务器示例，但这还不是可上线的完整应用。请在 BotFather 中填写 HTTPS URL，测试启动流程，并在发布前实现必要的后端校验、数据持久化和错误处理。应用稳定后，再单独测试广告。

调试和测试

Mini App 开发完成后，在部署前进行全面调试和测试至关重要。Telegram 提供了多种工具和方法，帮助你在开发过程中发现并解决问题。

测试方法

可以根据你的设置在不同阶段进行测试。本地开发时，可使用 VS Code 中的 Live Server 等工具在本地服务器上运行应用。使用测试环境时，可通过 HTTP 链接和 IP 地址访问应用，方便快速测试。如需接近生产环境的测试，可部署到 Vercel、Netlify 或 Heroku 等预发布平台，查看 Mini App 在真实 Telegram 条件下的表现。

调试工具

使用浏览器开发者工具进行控制台、网络和 JavaScript 调试。Telegram 的检查支持取决于客户端、平台和调试设置，请按照适用于你版本的最新 Mini Apps 调试说明操作。检查 Android 和 iOS 的 WebView 可能需要额外设置。

常见问题及解决方法

部署前测试清单

上线前，请确认所有核心功能运行正常，包括用户身份验证、交互元素和 API 集成。确保错误处理能向用户提供恰当的反馈，并在不同屏幕尺寸和设备上进行测试。监控加载时间和响应速度，以保证流畅的性能。

生产环境监控

上线后，请使用 Sentry 或 LogRocket 等监控工具跟踪错误和性能。监控 API 响应时间，跟踪用户行为，并为严重问题设置告警。定期监控有助于快速发现和解决问题，保持高质量的服务。

HTTPS 要求和部署注意事项

了解 HTTPS 要求对成功部署 Mini App 至关重要。Telegram 在生产环境中执行严格的安全标准，满足这些要求可以避免最常见的部署问题。

各环境的 HTTPS 要求

Telegram 要求所有生产环境的 Mini Apps 使用 HTTPS，以加密用户信息、身份验证令牌和 API 请求等敏感数据。测试环境允许在本地开发时使用 HTTP URL 和 IP 地址（例如 http://192.168.1.100:3000）。生产环境则严格要求使用带有效 SSL 证书的 HTTPS，HTTP URL 会被拒绝。

获取 SSL 证书

许多托管平台提供托管式 HTTPS，但费用、证书支持和自定义域名要求因产品和套餐而异：

• Vercel – 自动 SSL，即时提供 HTTPS URL，非常适合 React/Next.js 应用。
• Netlify – 免费 SSL 证书，持续部署，非常适合静态网站。
• Heroku – HTTPS 和自定义域名证书管理取决于部署方式和套餐；不要默认每个套餐都提供免费托管或自动证书。
• AWS/DigitalOcean – 根据所选托管产品，可能提供托管证书或手动配置。

Let’s Encrypt 提供可手动安装的免费证书。商业服务商（DigiCert、Sectigo）提供付费证书，但大多数 Mini Apps 通常并不需要。

常见问题及解决方法

部署流程

开发阶段： 在测试环境中使用 HTTP 和本地服务器，快速迭代。

预生产： 部署到支持自动 HTTPS 的托管服务，核实 SSL 证书，在测试环境中通过 HTTPS 测试，并确保所有外部资源都使用 HTTPS。

生产： 在 BotFather 中更新 HTTPS URL，跨平台测试，监控证书有效期，并启用自动续期。

最佳实践

将服务器密钥保存在环境变量中，合理限制 API 访问，并使用 HTTPS。CORS 不能验证请求身份。请检查 DNS 和证书续期；证书签发时间不固定，也不保证在特定分钟数内完成。

HTTPS 是生产环境 Mini Apps 的基本要求。选择提供自动 SSL 的托管平台，有助于高效满足 Telegram 的安全标准。

如何将 Mini App 添加到 Telegram？

Mini App 准备就绪并通过测试后，就可以将它添加到 Telegram 供用户使用了。了解 Telegram Mini Apps 的工作原理，是成功集成的关键。

第 1 步：将项目上传到服务器

第一步是将 Mini App 放到服务器上，这样用户才能随时使用。服务器能让应用持续运行并实时处理请求。具体做法如下：

为各个组件选择合适的托管方式：界面使用静态托管，机器人使用长期运行的进程或支持 webhook 的函数。请查看最新价格，不要默认 Heroku 或其他平台是免费的。从代码仓库部署时，不要公开机器人令牌或其他密钥。

部署完成后，托管服务会提供一个应用 URL，你的 Mini App 可通过它在线访问。

第 2 步：连接机器人并配置应用 URL

托管完成后，在 BotFather 的应用或菜单按钮设置中填写 Mini App 的 HTTPS URL。机器人令牌用于服务器之间的 Bot API 调用，不是可以嵌入网页界面的访问密钥。

请仅将 BOT_TOKEN 保存在机器人服务器的环境中。Telegram 机器人更新和 Mini App 浏览器请求是两条独立的流程：显示 Web 应用并不需要让每次点击都经过机器人。生产环境请使用 HTTPS，并在涉及用户身份时在后端校验 initData。

第 3 步：设置和应用集成

要让 Mini App 在 Telegram 中完整运行，需要正确配置系统，并添加可供用户互动的元素。请确保应用直接在 Telegram 内启动，以提供最佳用户体验。

配置 webhook

Webhook 接收机器人的 Bot API 更新，不会自动接收 Mini App 中每次浏览器点击。仅在选择 webhook 而非轮询时才需要配置。不要对同一个机器人同时使用 getUpdates 轮询和有效的 webhook。

设置按钮和命令

为了让用户轻松启动 Telegram Mini App，请添加直观的按钮和命令。例如，可以使用“启动”“打开”或其他与应用功能相对应的按钮。可以考虑添加菜单按钮以便导航，它也可以用作机器人菜单按钮。有了这些按钮，用户无需输入文本命令，就能直接在聊天中与 Mini App 互动。Telegram 界面应提供流畅的交互，机器人也应顺畅处理所有这些操作。

设置可触发应用中特定操作的命令，例如启动游戏或获取帮助。请确保正确处理每个参数。

处理命令和操作

应用必须正确响应用户操作。当用户点击按钮或输入命令时，应用应发送相应回复或启动 Mini App 的对应功能，这样才能保证交互流畅方便。机器人也应能够处理各种场景和边缘情况。

第 4 步：测试和上线

一切设置完成后，就可以测试 Mini App 了：

确认服务器运行正常，并可通过 HTTPS 在线访问。登录 Telegram 并打开应用。点击已配置的按钮，确认应用按预期运行。确认它能正确响应命令并与系统交互。

设置完成后，请确认目标用户可以访问应用，并确认权限、后端服务和地区可用性都正确。在扩大发布范围之前，请先监控错误和实际使用情况。

通过 BotFather 设置 Mini App

开发完成后，需要正确配置应用。构建 Telegram Mini App 时，遵循正确的步骤至关重要。应用准备就绪后，就可以进行最后的配置了。

返回 BotFather 配置 Mini App 设置。你可以创建供用户分享的直接链接，并确保应用在 Telegram 群组中运行良好。Telegram 平台同时支持 Android 和 iOS 设备，因此请确保应用兼容这两个系统。

设计应用时请参考 Telegram 界面规范。无论使用什么设备，用户打开 Mini App 时都应获得流畅的体验。请优化 Mini App，并充分利用可用功能。

用户可以直接通过 Telegram 界面访问应用，获得最佳体验。添加所有必要功能后，它将成为为用户提供完整服务的解决方案。

使用 AdsGram 推广 Mini App

Mini App 上线后，你可以使用 AdsGram 进行推广。我们的平台可以专门为 Telegram Mini Apps 和游戏设置广告。你也可以使用 Telegram Ads 扩大覆盖范围。你可以：

创建广告活动，为应用吸引更多用户。使用地域定向，在合适的地区投放广告，获取优质流量。针对游戏和 Mini Apps 优化激励视频或横幅等广告形式，提升用户参与度。

借助 AdsGram，你可以有效推广应用并吸引新用户。祝你的 Mini App 上线和推广顺利！