MasLogin · 博客

用 Telegram Mini App 打造免Gas Web3 小游戏实战

日期 2025-12-10MasLogin预计阅读 7 分钟

最近 Telegram 正式向开发者开放了 Mini App（小程序） 能力,这意味着你可以在 Telegram 内打造原生应用级的互动体验。而今天,我们要带你一步步构建一款简单但完整的 Web3 小游戏,用户只需输入邮箱即可创建钱包、玩石头剪刀布游戏并领取代币奖励——全程无需用户支付 Gas 费用。

本文目录

MasLogin

专业指纹浏览器，面向规模化多账号运营

独立浏览器环境
RPA 自动化
团队协作

免费下载

这篇教程不仅会教你如何创建并部署一个 Telegram Mini App,还会展示如何用 thirdweb SDK 的免费功能,实现账户抽象(Account Abstraction)、钱包创建、Token 空投等 Web3 核心能力。

为什么选择 Telegram Mini App 做 Web3 项目?

天然的社交流量 + 零门槛体验

Telegram 拥有超 8 亿月活跃用户,支持全球开发者免费部署应用。对于 Web3 项目来说,Telegram Mini App 的优势在于:

无需下载安装:用户直接在 Telegram 内使用
社交裂变快:分享链接即可拉新
技术栈统一:基于 Web 技术,支持 React/Vue 等主流框架
适配移动端:天然适配手机与桌面客户端

结合 账户抽象技术,你可以让用户无需下载钱包插件,仅用邮箱即可拥有链上钱包——这对降低 Web3 项目的用户门槛至关重要。

我们要构建什么?一个完整的 Web3 石头剪刀布游戏

这款游戏的核心流程是:

用户在 Telegram 内打开 Mini App
用邮箱登录,自动生成智能合约钱包(Smart Account)
玩石头剪刀布游戏
赢了之后点击"领取奖励",免费获得代币到钱包
余额实时显示,可以继续玩或退出

整个过程不需要用户支付任何 Gas 费,也不会弹出复杂的签名确认框——这就是 账户抽象 + 赞助 Gas 带来的真实 Web3 无感体验。

核心技术选型与工具

前端框架

Vite + React:快速搭建页面
TypeScript:提升代码健壮性

Web3 能力集成

thirdweb SDK:提供钱包连接、账户抽象、合约交互
vov/react-telegram-web-app:Telegram 官方适配库

区块链网络

Base Sepolia Testnet(测试网):免费、快速,适合开发演示

开发辅助

ngrok:让本地开发环境可通过公网访问,方便调试

第一步:创建 Telegram Mini App

1. 添加 BotFather 并创建 Bot

在 Telegram 搜索框输入 @BotFather,找到官方机器人并点击"开始"。

输入命令创建新 Bot:

/newbot

按提示输入名称和用户名(必须以 bot 结尾),例如:

名称: thirdweb YouTube Demo
用户名: thirdwebYouTubeBot

创建成功后,BotFather 会返回一个 Token——请妥善保存,这是你管理 Bot 的凭证。

2. 创建 Mini App

继续在 BotFather 输入:

/newapp

选择你刚才创建的 Bot,然后依次填写:

标题:thirdweb Rock Paper Scissors Demo
简介:Web3 Rock Paper Scissors Mini Game
图片:上传一张封面图(尺寸建议 640×360)
Web App URL:暂时留空,我们稍后填写

此时,Telegram 会提示你提供 Mini App 的访问链接。现在我们先开发应用,再填这个字段。

第二步:搭建本地开发环境

初始化项目

打开终端,运行:

bun create vite

选择:

项目名:thirdweb-telegram-miniapp
框架:React
变体:TypeScript + SWC

进入项目目录:

cd thirdweb-telegram-miniapp

安装依赖

安装 Telegram Web App 适配库:

bun add @vov/react-telegram-web-app

安装 thirdweb SDK:

bun add thirdweb

配置 Telegram 脚本

打开 index.html,在 <head> 标签内添加:

<script src="https://telegram.org/js/telegram-web-app.js"></script>

这段代码告诉 Telegram,你的网页需要在 Mini App 环境中运行。

启动开发服务器

npm run dev

默认会在 http://localhost:5174 启动服务。

第三步:用 ngrok 暴露本地链接

因为 Telegram 需要一个公网 URL 才能访问你的 Mini App,我们用 ngrok 工具临时将本地服务暴露到外网。

运行:

ngrok http 5174

ngrok 会返回一个公网地址,例如:

https://abc123.ngrok.io

复制这个链接,回到 BotFather,粘贴到 Web App URL 字段。

现在点击 Telegram 里的 Mini App 链接,应该就能看到你的 Vite 默认页面了!

第四步:集成 thirdweb SDK 与钱包连接

创建 Client ID

前往 thirdweb Dashboard,在 Settings > API Keys 创建一个新的 Client ID。

将 Client ID 复制到项目根目录的 .env.local 文件:

VITE_CLIENT_ID=your_client_id_here

配置 thirdweb Provider

在 src/main.tsx 中包裹应用:

import { ThirdwebProvider } from "thirdweb/react";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({
  clientId: import.meta.env.VITE_CLIENT_ID,
});

root.render(
  <ThirdwebProvider>
    <App />
  </ThirdwebProvider>
);

添加邮箱登录功能

使用 thirdweb 提供的 ConnectButton 组件:

import { ConnectButton } from "thirdweb/react";
import { inAppWallet } from "thirdweb/wallets";

<ConnectButton
  client={client}
  wallets={[
    inAppWallet({
      auth: {
        options: ["email"],
      },
    }),
  ]}
/>

用户输入邮箱 → 收到验证码 → 验证成功后自动生成钱包 → 完成!

第五步:构建石头剪刀布游戏逻辑

在 src/components/RockPaperScissors.tsx 中实现核心逻辑:

type Choice = "rock" | "paper" | "scissors";
type Result = "win" | "lose" | "tie";

const choices: Choice[] = ["rock", "paper", "scissors"];

const getComputerChoice = (): Choice => {
  return choices[Math.floor(Math.random() * 3)];
};

const determineWinner = (player: Choice, computer: Choice): Result => {
  if (player === computer) return "tie";
  if (
    (player === "rock" && computer === "scissors") ||
    (player === "paper" && computer === "rock") ||
    (player === "scissors" && computer === "paper")
  ) {
    return "win";
  }
  return "lose";
};

用户点击按钮 → 随机生成电脑选择 → 判断胜负 → 显示结果。

第六步:部署 ERC-20 代币合约

回到 thirdweb Dashboard,点击 Contracts > Deploy,选择 Token Drop。

配置:

名称:Rock Paper Scissors Token
符号:RPS
网络:Base Sepolia

部署成功后,在 Claim Conditions 设置为"公开领取,无限制"。

复制合约地址,在代码中添加:

import { getContract } from "thirdweb";
import { baseSepolia } from "thirdweb/chains";

const contract = getContract({
  client,
  chain: baseSepolia,
  address: "0xYourContractAddress",
});

第七步:实现账户抽象 + 免 Gas 领取代币

启用账户抽象

在 ConnectButton 中添加:

<ConnectButton
  client={client}
  wallets={[inAppWallet({ auth: { options: ["email"] } })]}
  accountAbstraction={{
    chain: baseSepolia,
    sponsorGas: true,
  }}
/>

这样用户生成的钱包就是 智能合约钱包(Smart Account),我们可以代付 Gas 费。

领取代币按钮

import { TransactionButton } from "thirdweb/react";
import { claimTo } from "thirdweb/extensions/erc20";

<TransactionButton
  transaction={() =>
    claimTo({
      contract,
      to: account.address,
      quantity: "10",
    })
  }
  onTransactionConfirmed={() => alert("代币已领取!")}
>
  领取 10 RPS
</TransactionButton>

用户点击按钮 → thirdweb 自动处理交易 → 代币到账 → 无需用户支付任何费用!

第八步:显示余额与登出功能

读取代币余额

import { useReadContract } from "thirdweb/react";
import { getBalance } from "thirdweb/extensions/erc20";

const { data: tokenBalance } = useReadContract(getBalance, {
  contract,
  address: account.address,
});

<div>余额: {tokenBalance?.displayValue} RPS</div>

添加退出按钮

import { useDisconnect, useActiveWallet } from "thirdweb/react";

const wallet = useActiveWallet();
const { disconnect } = useDisconnect();

<button onClick={() => disconnect(wallet)}>退出登录</button>

在移动端测试完整流程

在手机上打开 Telegram,搜索你的 Bot,点击 Mini App 链接:

输入邮箱 → 验证 → 钱包生成
玩游戏 → 赢了之后点击"领取奖励"
代币到账,余额更新
无需任何插件或签名操作!

FAQ

这个方案免费吗?

本教程使用的所有 thirdweb 功能都在免费计划内,包括钱包创建、合约交互、账户抽象等。如果你需要用 Telegram 账号直接登录(无需邮箱验证),则需要升级到付费计划。

如何避免用户重复领取代币?

你可以在智能合约中添加逻辑限制每个地址的领取次数,或使用 thirdweb 的 Claim Conditions 功能设置白名单、时间窗口等规则。

能否换成其他区块链?

完全可以。只需在 getContract 和 accountAbstraction 配置中替换为你想要的链(如 Polygon、Arbitrum 等)。thirdweb 支持超过 900 条 EVM 兼容链。

如何部署到生产环境?

将代码部署到 Vercel、Netlify 等平台,获取正式域名后替换 BotFather 中的 Web App URL 即可。

赞助 Gas 费用会不会很贵?

thirdweb 的免费计划每月提供一定额度的赞助 Gas,对于小型项目或测试完全够用。如果流量大,可以根据实际需求升级。

总结

通过这篇教程,你已经掌握了如何在 Telegram 内构建一个完整的 Web3 应用——从钱包创建、游戏逻辑到代币分发,全部无缝集成。这套技术栈不仅适用于小游戏,还可以扩展到 DeFi、NFT、社交应用等更多场景。