Telegram Mini App 测试教程:从浏览器模拟到真实 Telegram 客户端
Telegram Mini App 测试一般分几步:先在普通浏览器中用模拟的 Telegram.WebApp 调好界面,再把本地构建通过 HTTPS 暴露出去、在 @BotFather 中注册 URL,然后在 Telegram 里连上 DevTools 调试。最后一步在服务器端完成:信任用户身份之前必须先校验 initData。下面按顺序介绍从 localhost 到上线检查清单的完整流程。
第 1 步:在普通浏览器中测试界面
在 Telegram 之外,Telegram.WebApp 背后没有客户端:没有启动数据、没有主题、也没有原生按钮。不过只要代码能兼容这种情况,大部分界面都可以在桌面浏览器里开发:
const tg = window.Telegram?.WebApp;
const insideTelegram = Boolean(tg?.initData);
if (insideTelegram) {
tg.ready(); // 尽早隐藏加载占位
tg.expand();
} else {
console.info("不在 Telegram 内:使用模拟数据");
}
样式中使用主题变量并加上默认值,例如 var(--tg-theme-bg-color, #fff),这样页面在两种环境下都清晰可读。
如果想不写代码就看到每个 API 调用的效果,可以打开 Mini App Tester。它在普通浏览器中以模拟模式运行,模拟 Telegram.WebApp:可以点击 MainButton 和 BackButton、打开弹窗、写入 CloudStorage、切换主题,并在日志中查看 45 种以上的事件。但模拟数据只是替身:它的 initData 没有经过 Telegram 签名,服务器端校验时会(理所当然地)失败。
第 2 步:通过 HTTPS 在 localhost 运行 Telegram Mini App
Telegram 只打开 HTTPS 地址的 Mini App(测试环境除外),而且手机本来也访问不到 http://localhost。在 localhost 上测试 Telegram Mini App 的常规做法是使用隧道(内网穿透),给开发服务器分配一个公网 HTTPS 地址:
# 启动开发服务器,例如端口为 5173 的 Vite
npm run dev
# 在第二个终端中任选一种隧道工具
ngrok http 5173
cloudflared tunnel --url http://localhost:5173
两个工具都会输出一个公网 https:// 地址。常见的两个坑:
- Vite 拒绝隧道域名。较新版本的 Vite 开发服务器会拦截未知的 Host,需要把隧道域名加到
vite.config.js的server.allowedHosts中。 - 地址会变。很多隧道每次重启都会分配新的随机地址。这时要在 @BotFather 中更新,或重新执行第 3 步的
setChatMenuButton调用。
第 3 步:在 @BotFather 中注册 Mini App
Mini App 总是属于某个机器人。还没有机器人的话,请先阅读 创建 Telegram 机器人教程。然后选择用户打开你的 URL 的方式:
- 直达链接:向 @BotFather 发送
/newapp,选择机器人并按提示操作。之后应用可以通过https://t.me/<bot_username>/<app_name>打开。 - 菜单按钮:在 @BotFather 中使用
/setmenubutton或 Bot Settings → Menu Button,也可以调用setChatMenuButton方法。 - 键盘按钮:回复键盘或内联键盘中的
web_app按钮(仅限私聊)。
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button": {"type": "web_app", "text": "打开应用",
"web_app": {"url": "https://your-tunnel.example.com"}}}'
不传 chat_id 时,设置的是所有用户的默认菜单按钮。隧道地址每次变化后,可以直接在 Bot API Tester 的 setChatMenuButton 中重新调用,不必反复手敲 curl。
第 4 步:使用 Telegram 测试环境
Telegram 提供独立的测试环境,其中 Mini App 链接可以使用不带 TLS 的普通 HTTP,在局域网内测试很方便。测试环境需要单独的账号和单独的机器人:
- iOS:连续点击“设置”图标 10 次 → Accounts → Login to another account → Test。
- Telegram Desktop:☰ 设置 → Shift+Alt+右键点击“Add Account” → Test Server。
- macOS:连续点击“设置”图标 10 次打开 Debug Menu,然后 ⌘+点击“Add Account”。
在测试账号里通过 @BotFather 创建机器人,API 请求发往 https://api.telegram.org/bot<token>/test/METHOD_NAME。测试环境的频率限制并没有放宽,甚至可能更严格,所以不适合做压力测试。完整的配置方法(包括 Bot API Tester 中的 TEST 开关)见 Telegram 测试服务器使用教程。
第 5 步:在 Telegram 内调试 Mini App
很多在 Chrome 里从不出现的 bug,只会在真实的 WebView 中暴露。Telegram 官方的 Debug Mode for Mini Apps 说明概括如下:
| 平台 | 调试方法 |
|---|---|
| iOS | 连续点击“设置”图标 10 次,开启 Allow Web View Inspection;用 USB 连接 Mac,在 Safari 中打开“开发”→ 你的设备。 |
| Android | 开启 USB 调试;在 Telegram 设置页滑到底部,长按版本号两次,选择 Enable WebView Debug;在 Chrome 中打开 chrome://inspect/#devices。 |
| Telegram Desktop(Windows、Linux) | 安装 Beta 版;设置 → 高级 → 实验性设置 → Enable webview inspection;右键 → Inspect。 |
| Telegram for macOS | 安装 Beta 版;连续点击“设置”图标 5 次,开启 Debug Mini Apps;右键 → Inspect Element。 |
想快速对比不同客户端,可以把 https://telegram-bot-api.info/telegram-mini-app-tester.html 设为测试机器人的 Mini App URL。在 Telegram 内,Mini App Tester 调用的是真实 API,会显示 version、platform、colorScheme、themeParams、安全区域,以及当前客户端触发的所有事件。在自己的代码中,用 Telegram.WebApp.isVersionAtLeast("8.0") 判断后再使用新功能,不要假设所有用户都装了最新版。
第 6 步:在服务器端校验 initData
Telegram.WebApp.initDataUnsafe 只能用于展示。要把原始的 Telegram.WebApp.initData 字符串发给后端并校验:
- 解析查询字符串,去掉
hash。 - 将其余字段按字母顺序排序,拼成
key=value形式、以\n分隔的多行文本,这就是data_check_string。 - 计算
secret_key = HMAC_SHA256(key="WebAppData", message=bot_token)。 - 如果
hex(HMAC_SHA256(key=secret_key, message=data_check_string))等于hash,数据就是真实的。 - 检查
auth_date,拒绝过期的数据。
import crypto from "node:crypto";
export function validateInitData(initData, botToken, maxAgeSec = 3600) {
const params = new URLSearchParams(initData);
const hash = params.get("hash") ?? "";
params.delete("hash");
const dataCheckString = [...params.keys()].sort()
.map((key) => `${key}=${params.get(key)}`)
.join("\n");
const secretKey = crypto.createHmac("sha256", "WebAppData").update(botToken).digest();
const expected = crypto.createHmac("sha256", secretKey).update(dataCheckString).digest("hex");
const valid = hash.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
const age = Date.now() / 1000 - Number(params.get("auth_date"));
if (!valid || !(age <= maxAgeSec)) return null;
return { ...Object.fromEntries(params), user: JSON.parse(params.get("user") ?? "null") };
}
客户端原样提交这个字符串,例如 fetch("/api/session", { method: "POST", body: Telegram.WebApp.initData }),服务器端用启动该应用的机器人的 Token 校验。如果第三方需要验证数据但不能知道你的 Token,可以改用 Telegram 的 Ed25519 公钥验证 signature 字段,具体见官方文档。
Bot API 10.2:Mini App 来源保护
Bot API 10.2 禁止从 Mini App 原始域名以外的源调用 Mini App 方法,2026 年 7 月 20 日起该保护对所有 Mini App 启用。测试时最容易踩坑的情况是:应用从注册的隧道地址跳转到了另一个域名,比如预发布环境或登录页,Telegram.WebApp 的调用在那里就会失效。请把与 Telegram 交互的代码放在注册的域名上,隧道域名变化后记得重新注册 URL。也可以在 @BotFather 的 Mini App 设置中关闭这项保护,但那样就需要你自己确保 Mini App 中没有指向不可信网站的链接。
Telegram Mini App 测试检查清单
- 界面在模拟模式下以及浅色、深色主题下都正常。
- 关键界面渲染完成后立即调用
Telegram.WebApp.ready()。 - @BotFather 或
setChatMenuButton中的 URL 与当前的隧道地址或正式域名一致。 - 已在 iOS、Android 和桌面端连接 DevTools 测试;新功能用
isVersionAtLeast()做了判断。 - 全屏布局考虑了
safeAreaInset和contentSafeAreaInset。 - 后端校验
initData(hash和auth_date),从不信任initDataUnsafe。 - 所有
Telegram.WebApp调用都在注册的源上执行。 - 正式环境部署在自己的域名上并使用有效证书,而不是临时隧道。
校验代码依赖机器人 Token,务必妥善保管,参见 Telegram Bot Token 获取与保护教程。如果同一个后端还要接收机器人更新,请继续阅读 Telegram Bot Webhook 设置教程。如果你只需要在聊天消息中放一个小型交互模块,而不是完整的网页应用,可以看看 Bot API 10.4 新增的 Telegram 小组件。
常见问题
如何在 localhost 上测试 Telegram Mini App?
Telegram 只能打开 HTTPS 地址的 Mini App,所以要用 HTTPS 隧道(例如 ngrok 或 Cloudflare Tunnel)把本地开发服务器暴露到公网,再把这个地址填到 @BotFather 或通过 setChatMenuButton 设置。测试环境中允许使用普通 HTTP 链接。
不打开 Telegram 能测试 Mini App 吗?
可以测一部分。普通浏览器里没有 Telegram 客户端,需要模拟 Telegram.WebApp,例如使用 Mini App Tester 的模拟模式。真实的 initData、原生弹窗和触觉反馈只能在 Telegram 内使用。
怎样为 Telegram Mini App 打开 DevTools?
iOS:连续点击“设置”图标 10 次,开启 Allow Web View Inspection,然后用 Mac 上 Safari 的“开发”菜单调试。Android:在 Telegram 调试设置中开启 WebView Debug,再打开 chrome://inspect/#devices。桌面版和 macOS 版使用 Beta 客户端中的 WebView 调试选项。
initData 校验为什么总是失败?
常见原因:校验的是 initDataUnsafe 而不是原始 initData 字符串;用了其他机器人的 Token;没有对值做 URL 解码;hash 留在了 data-check 字符串里;把 HMAC 的 key 和 message 弄反;或者用的是 Telegram 从未签名过的模拟数据。
为什么 Telegram.WebApp 的方法在另一个域名下失效了?
从 Bot API 10.2 起,从与 Mini App 域名不同的源(origin)调用 Mini App 方法会被拦截,2026 年 7 月 20 日起该保护对所有 Mini App 生效。请让应用保持在注册的域名上,或者在 @BotFather 中关闭这项保护。
Telegram Mini App 有单独的测试服务器吗?
有。测试环境与正式环境完全隔离:需要在其中注册新账号和新机器人,Bot API 请求发往 https://api.telegram.org/bot<token>/test/METHOD_NAME,Mini App 链接可以使用不带 TLS 的 HTTP。
相关教程
Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息
Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。
Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案
Telegram 机器人部署与托管指南:轮询还是 Webhook,VPS 上的 systemd 服务、Docker 部署、带 secret_token 校验的 Cloudflare Workers,以及上线检查清单。
Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等
Telegram Bot API 10.0–10.5 更新了什么:setMySettings 与 BotFullInfo、HTML 小组件、富文本消息、临时消息、访客模式,附 JSON 示例与升级清单。
Telegram Bot API 错误码大全:每种报错的含义与解决方法
Telegram Bot API 常见错误详解:400 chat not found、403 bot was blocked by the user、409 Conflict、429 retry_after,逐一说明原因、解决方法,并附错误处理代码。
Telegram Bot API 限制汇总:发送频率、429 错误、文件大小与消息长度
Telegram Bot API 频率限制详解:每秒约 30 条、单聊每秒 1 条、群组每分钟 20 条,429 错误与 retry_after 处理代码,以及文件大小和消息长度限制。
Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接
Telegram 机器人命令配置教程:@BotFather /setcommands、按作用域和语言调用 setMyCommands、/start 深层链接参数,以及群组中的 /cmd@bot 用法。
Telegram 机器人键盘教程:内联键盘、回调按钮与回复键盘
Telegram 机器人按钮教程:用 callback_data 创建内联键盘、answerCallbackQuery 应答、点击后编辑消息,以及回复键盘和 ForceReply,附完整 Python 与 JS 示例。
n8n Telegram 集成教程:连接机器人、触发工作流并发送消息
n8n 对接 Telegram 机器人:把 bot token 填入 Access Token,Telegram Trigger 通过公网 HTTPS Webhook 接收消息,按 chat id 发送消息,以及常见报错的解决方法。
Telegram Bot API 发送消息教程:sendMessage 参数、格式、按钮与错误处理
Telegram Bot API 发送消息中文教程:sendMessage 参数说明,curl、Python、JavaScript 示例,HTML 与 MarkdownV2 格式、内联按钮、群组和频道发送,以及 400、403、429 错误处理。
Telegram Bot Token 怎么获取:获取、查看、验证和撤销机器人 Token
Telegram Bot Token 怎么获取?用 @BotFather 的 /newbot 获取新 Token,在 /mybots 中查看已有 Token,用 getMe 检查是否有效,泄露后及时撤销,并配合 chat_id 接入 n8n 等工具。
Telegram Bot Webhook 设置教程:用 setWebhook 配置 Webhook URL 和 secret_token
Telegram Bot API setWebhook 中文教程:Webhook URL 的 HTTPS 与端口要求、secret_token 请求头校验、用 getWebhookInfo 排错、用 deleteWebhook 切回轮询,以及 409 等常见错误的解决方法。
Telegram chat id 获取教程:查看用户、群组、频道和话题的聊天 ID
Telegram chat id 获取教程:用 getUpdates 查看私聊、群组、超级群组、频道和论坛话题的聊天 ID,讲清负数和 -100 前缀的含义,并排查 result 为空、409 Conflict 等常见问题,附 Python 示例。
Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询
Telegram 内联机器人(inline bot)开发教程:用 @BotFather 或 setMySettings 开启 Inline 模式,处理 inline_query 更新,并通过 answerInlineQuery 返回结果。
Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅
Telegram 机器人接入 Stars 支付:用 XTR 调用 sendInvoice,处理 pre_checkout_query 和 successful_payment,退款与订阅,附 Python/JS 代码。
Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人
Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 Telegram 机器人。
Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮
在网站上接入 Telegram:新版 Telegram 登录(OpenID Connect)、旧版 Login Widget 及 hash 校验代码、嵌入 Telegram 帖子、评论区小部件和分享按钮,附常见问题排查。
TelegramWidget JavaScript API:属性、事件、错误码与限制参考
TelegramWidget JavaScript API 中文参考:属性、request()、事件、错误码、CSS 变量,widget_query 与 answerWidgetQuery 的用法,以及小组件的全部限制。
Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码
可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。
Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML
Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。