Telegram Web App 的 HTML 限制包括：仅支持 HTTPS 请求、禁用 document.write/window.open/Notification 等 API，localStorage 不可靠，Geolocation 需显式授权；必须通过 WebApp.initData 获取用户身份，JS 需等 WebApp.ready() 后调用 SDK；视口高度应使用 WebApp.viewportStableHeight；所有交互须用 WebApp 提供的方法（如 openTelegramLink/sendData/showAlert）；本地 HTTP/file 协议无法初始化 SDK，调试必须部署到 HTTPS 域名并真机测试。
Telegram Web App 的 HTML 限制有哪些
Telegram Web App 不是普通网页，它运行在 Telegram 客户端内嵌的 WebView 中（iOS 用 WKWebView，Android 用 Chromium-based WebView），所以很多浏览器 API 被禁用或行为异常。document.write、window.open、localStorage（部分版本不可写）、Notification、Geolocation（需显式授权且常被拦截）基本不能用。更关键的是：**所有网络请求必须走 HTTPS，且跨域策略由 Telegram 控制，不是标准 CORS**。
常见错误现象：Failed to execute 'fetch' on 'Window': Request scheme 'http' is not supported；SecurityError: localStorage is not available for this document；点击按钮无响应——其实是 onclick 绑定成功了，但后续调用的 WebApp.showAlert 因未初始化而静默失败。
- 必须通过
WebApp.initData或WebApp initDataUnsafe获取用户身份，不能依赖 Cookie 或 Session - 所有 JS 必须等
WebApp.ready()后才能调用 SDK 方法，否则多数接口返回undefined或抛错 - 页面尺寸由 Telegram 控制：
WebApp.viewportStableHeight才是可靠视口高度，window.innerHeight在键盘弹出/收起时严重滞后
如何正确加载和初始化 WebApp SDK
别直接写 <script src="https://telegram.org/js/telegram-web-app.js"></script> 就完事。Telegram 官方 SDK 不提供 CDN 版本，实际应使用 <script async src="https://telegram.org/js/telegram-web-app.js"></script>（这是唯一合法入口），但它只挂载全局 WebApp 对象，不自动执行任何逻辑。
初始化必须手动触发，且时机敏感：
立即学习“前端免费学习笔记（深入）”；
- 在
<head>中加载 SDK 脚本后，**不要立即调用WebApp.ready()**——脚本可能未就绪 - 推荐写法：监听
DOMContentLoaded，再用setTimeout(..., 0)或queueMicrotask确保 SDK 已注入 - 必须检查
WebApp.initData是否存在，空值意味着没从 Telegram 内打开（比如直接粘贴 URL 测试），此时应跳转提示页或降级渲染
示例片段：
document.addEventListener('DOMContentLoaded', () => {
if (typeof WebApp === 'undefined') return;
queueMicrotask(() => {
if (WebApp.initData) {
WebApp.ready();
WebApp.expand(); // 主动撑满视口
} else {
document.body.innerHTML = '<p>请在 Telegram 中打开</p>';
}
});
});
HTML 元素如何适配 Telegram 的交互规范
Telegram Web App 强制接管了原生滚动、弹窗、导航等行为。你写的 <button> 没问题，但 <a href="/next"> 会直接跳出 Web App（变成外部浏览器打开），input[type="file"] 在 iOS 上几乎不可用，textarea 长按菜单会被 Telegram 截获。
核心原则：**放弃“网页思维”，只用 Web App 提供的交互通道**。
- 跳转用
WebApp.openTelegramLink('https://t.me/username')，不是window.location - 表单提交后，用
WebApp.sendData(JSON.stringify(payload))把数据传回 Bot，而不是发 AJAX - 弹窗统一用
WebApp.showAlert()/WebApp.showConfirm()，别自己写 modal - 颜色主题要响应
WebApp.colorScheme（'light'/'dark'），并监听themeChanged事件重绘
容易踩的坑：WebApp.close() 只在用户主动点击「关闭」按钮时才生效，JS 主动调用无效；WebApp.setHeaderColor('#2a88f0') 在深色模式下可能被忽略，得配合 WebApp.setBackgroundColor() 一起设。
为什么本地开发时样式错乱、按钮点不动
根本原因：本地 file:// 协议或 HTTP 服务（如 localhost:3000）无法触发 Telegram SDK 初始化。SDK 只在 https://t.me/yourbot/app 这类合法上下文中注入 WebApp 对象并开放 API。
调试必须走真实链路：
- 部署到 HTTPS 域名（哪怕只是 Vercel/Cloudflare Pages 的免费域名），然后在 BotFather 设置
/setwebapp指向该地址 - 真机测试！模拟器或桌面 Telegram Desktop 对 Web App 支持极差，尤其是键盘弹出逻辑和 viewport 计算
- 开启 Telegram 的开发者工具：Android 上长按任意消息 → “Developer mode”，iOS 上设置 → “Data and Storage” → “Developer Mode” → 开启后摇动手机唤出调试面板
最常被忽略的一点：Telegram 会缓存 Web App 的 JS/CSS 资源，且不遵循 Cache-Control。改完代码后，务必强制刷新——在 Telegram 内长按页面空白处，选 “Reload”（不是下拉刷新），否则永远在跑旧版本。
