如何构建 Telegram Mini App (TWA) 并集成 TON 生态 #

解决开发者在 Telegram 生态内快速构建原生体验 Web 应用的难题，提供从基础 API 调用、TON 钱包集成到安全鉴权及病毒式增长机制的完整实现方案。

为什么需要这个技能 #

Telegram Mini Apps (TWA) 允许开发者在 8 亿用户量级的社交平台中直接运行 Web 应用，无需用户跳出 App。与传统网页不同，TWA 需要深度适配 Telegram 的 UX 范式（如 MainButton、HapticFeedback）并处理特定的安全校验。

同时，得益于 TON 区块链的集成，TWA 成为了目前最快速实现 Web3 落地、加密货币支付和“点击赚币”（Tap-to-Earn）游戏的最佳入口。

适用场景 #

• Web3 应用：构建 DeFi 工具、NFT 市场或基于 TON 的钱包管理工具。
• 社交游戏：开发具备邀请机制、排行榜和每日奖励的病毒式传播小游戏。
• 商业化服务：利用 Telegram Stars 或 TON 支付实现数字产品销售。
• 企业工具：在 Telegram 内部提供轻量级 CRM 或预约系统。

核心工作流 #

1. 基础环境搭建 #

引入官方 JS SDK 并初始化应用，确保应用能够正确适配 Telegram 的主题颜色和视口大小。

<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script>
  const tg = window.Telegram.WebApp;
  tg.ready();
  tg.expand(); // 展开至全屏
</script>

2. 安全鉴权（后端校验） #

绝对禁止在后端直接信任前端传来的 initDataUnsafe。必须通过 initData 的哈希值与 Bot Token 进行服务端校验，防止用户伪造身份。

// Node.js 校验核心逻辑
const secretKey = crypto.createHmac('sha256', 'WebAppData').update(botToken).digest();
const calculatedHash = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest('hex');
if (calculatedHash !== hash) throw new Error('Invalid initData');

3. TON 钱包与支付集成 #

使用 @tonconnect/ui-react 快速实现钱包连接，并通过 sendTransaction 发起 TON 代币支付。

import { TonConnectButton, useTonConnectUI } from '@tonconnect/ui-react';

function PaymentButton({ amount, to }) {
  const [tonConnectUI] = useTonConnectUI();
  const handlePay = async () => {
    const transaction = {
      validUntil: Math.floor(Date.now() / 1000) + 60,
      messages: [{ address: to, amount: (amount * 1e9).toString() }]
    };
    await tonConnectUI.sendTransaction(transaction);
  };
  return <button onClick={handlePay}>Pay {amount} TON</button>;
}

4. 适配原生 UX 模式 #

使用 tg.MainButton 处理主提交动作，并利用 HapticFeedback 提升交互质感。

tg.MainButton.setText('确认支付');
tg.MainButton.show();
tg.HapticFeedback.impactOccurred('light');

下载和安装 #

下载 telegram-mini-app 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要 #

暂无推荐