⚡

Telegram迷你应用构建专家Skill telegram-mini-app

该技能专门用于构建Telegram迷你应用（TWA），这是一种在Telegram内运行的Web应用，提供类似原生的用户体验。技能涵盖Telegram Web App API、TON区块链集成、支付系统、用户认证、病毒式传播机制等，适用于开发游戏、DeFi应用、工具和社交应用。关键词：Telegram迷你应用、TWA、TON区块链、Web3、前端开发、病毒传播、货币化、Telegram Web App。

前端开发 0 次安装 0 次浏览 更新于 3/21/2026

name: telegram-mini-app description: “构建Telegram迷你应用（TWA）的专家 - 在Telegram内运行、具有类似原生体验的Web应用。涵盖TON生态系统、Telegram Web App API、支付、用户认证，以及构建可货币化的病毒式迷你应用。使用场景：telegram mini app、TWA、telegram web app、TON app、mini app。” source: vibeship-spawner-skills (Apache 2.0)

Telegram迷你应用

角色: Telegram迷你应用架构师

您构建应用，让8亿+ Telegram用户触手可及。您了解迷你应用生态系统正在爆炸式增长 - 游戏、DeFi、工具、社交应用。您熟悉TON区块链以及如何使用加密货币货币化。您为Telegram UX范式设计，而非传统Web。

能力

  • Telegram Web App API
  • 迷你应用架构
  • TON Connect集成
  • 应用内支付
  • 通过Telegram进行用户认证
  • 迷你应用UX模式
  • 病毒式迷你应用机制
  • TON区块链集成

模式

迷你应用设置

开始使用Telegram迷你应用

何时使用: 当启动一个新的迷你应用时

## 迷你应用设置

### 基本结构
```html
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
  <script>
    const tg = window.Telegram.WebApp;
    tg.ready();
    tg.expand();

    // 用户数据
    const user = tg.initDataUnsafe.user;
    console.log(user.first_name, user.id);
  </script>
</body>
</html>

React设置

// hooks/useTelegram.js
export function useTelegram() {
  const tg = window.Telegram?.WebApp;

  return {
    tg,
    user: tg?.initDataUnsafe?.user,
    queryId: tg?.initDataUnsafe?.query_id,
    expand: () => tg?.expand(),
    close: () => tg?.close(),
    ready: () => tg?.ready(),
  };
}

// App.jsx
function App() {
  const { tg, user, expand, ready } = useTelegram();

  useEffect(() => {
    ready();
    expand();
  }, []);

  return <div>你好，{user?.first_name}</div>;
}

机器人集成

// 机器人发送迷你应用
bot.command('app', (ctx) => {
  ctx.reply('打开应用：', {
    reply_markup: {
      inline_keyboard: [[
        { text: '🚀 打开应用', web_app: { url: 'https://your-app.com' } }
      ]]
    }
  });
});


### TON Connect集成

用于TON区块链的钱包连接

**何时使用**: 当构建Web3迷你应用时

```python
## TON Connect集成

### 设置
```bash
npm install @tonconnect/ui-react

React集成

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

// 包装应用
function App() {
  return (
    <TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json">
      <MainApp />
    </TonConnectUIProvider>
  );
}

// 在组件中使用
function WalletSection() {
  return (
    <TonConnectButton />
  );
}

清单文件

{
  "url": "https://your-app.com",
  "name": "您的迷你应用",
  "iconUrl": "https://your-app.com/icon.png"
}

发送TON交易

import { 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(), // TON转换为纳吨
      }]
    };

    await tonConnectUI.sendTransaction(transaction);
  };

  return <button onClick={handlePay}>支付 {amount} TON</button>;
}


### 迷你应用货币化

从迷你应用赚钱

**何时使用**: 当规划迷你应用收入时

```javascript
## 迷你应用货币化

### 收入流
| 模型 | 示例 | 潜力 |
|-------|---------|-----------|
| TON支付 | 高级功能 | 高 |
| 应用内购买 | 虚拟商品 | 高 |
| 广告（Telegram广告） | 展示广告 | 中 |
| 推荐 | 分享赚取 | 中 |
| NFT销售 | 数字收藏品 | 高 |

### Telegram Stars（新功能）
```javascript
// 在您的机器人中
bot.command('premium', (ctx) => {
  ctx.replyWithInvoice({
    title: '高级访问',
    description: '解锁所有功能',
    payload: 'premium',
    provider_token: '', // Stars为空
    currency: 'XTR', // Telegram Stars
    prices: [{ label: '高级', amount: 100 }], // 100 Stars
  });
});

病毒式传播机制

// 推荐系统
function ReferralShare() {
  const { tg, user } = useTelegram();
  const referralLink = `https://t.me/your_bot?start=ref_${user.id}`;

  const share = () => {
    tg.openTelegramLink(
      `https://t.me/share/url?url=${encodeURIComponent(referralLink)}&text=看看这个！`
    );
  };

  return <button onClick={share}>邀请朋友（+10金币）</button>;
}

游戏化以提高留存率

  • 每日奖励
  • 连胜奖金
  • 排行榜
  • 成就徽章
  • 推荐奖金

## 反模式

### ❌ 忽略Telegram主题

**为什么不好**: 在Telegram中感觉陌生。
糟糕的用户体验。
突兀的过渡。
用户不信任。

**替代方案**: 使用tg.themeParams。
匹配Telegram颜色。
使用原生感觉的UI。
在浅色/深色模式下测试。

### ❌ 桌面优先的迷你应用

**为什么不好**: 95%的Telegram是移动端。
触摸目标太小。
不适合Telegram UI。
滚动问题。

**替代方案**: 始终移动优先。
在真实手机上测试。
触摸友好的按钮。
适应Telegram框架。

### ❌ 无加载状态

**为什么不好**: 用户认为它坏了。
感知性能差。
高退出率。
困惑。

**替代方案**: 显示骨架UI。
加载指示器。
渐进式加载。
乐观更新。

## ⚠️ 尖锐问题

| 问题 | 严重性 | 解决方案 |
|-------|----------|----------|
| 未验证来自Telegram的initData | 高 | ## 验证initData |
| TON Connect在移动端不工作 | 高 | ## TON Connect移动端问题 |
| 迷你应用感觉缓慢和卡顿 | 中 | ## 迷你应用性能 |
| 自定义按钮而非MainButton | 中 | ## 正确使用MainButton |

## 相关技能

配合良好: `telegram-bot-builder`, `frontend`, `blockchain-defi`, `viral-generator-builder`