Telegram小程序中使用tonconnect/ui-react连接内置钱包异常

问题描述 #

基于React/Next.js开发Telegram小程序，使用@tonconnect/ui-react实现「连接钱包」功能，Tonkeeper等第三方钱包连接完全正常，但连接Telegram内置钱包时，界面显示连接成功提示，实际未建立有效连接，wallet状态始终为null。

简化代码实现 #

import { useTonConnectUI } from '@tonconnect/ui-react';
import { useState, useEffect, useCallback } from 'react';

const MAX_RETRIES = 3;
const RETRY_DELAY = 1000; // 1 second

export function useTonWallet() {
  const [tonConnectUI] = useTonConnectUI();
  const [wallet, setWallet] = useState(null);
  const [isConnecting, setIsConnecting] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    const unsubscribe = tonConnectUI.onStatusChange(walletInfo => {
      setWallet(walletInfo);
      setIsConnecting(false);
    });

    // Try to restore the connection
    tonConnectUI.setConnectRequestParameters({
      state: 'ready',
    });

    return () => {
      unsubscribe();
    };
  }, [tonConnectUI]);

  const connect = useCallback(async (retryCount = 0) => {
    setIsConnecting(true);
    setError(null);

    try {
      console.log('Attempting to connect wallet...');
      await tonConnectUI.connectWallet();
      console.log('Wallet connected successfully');
    } catch (error) {
      console.error('Failed to connect wallet:', error);

      if (error.message === 'Failed to fetch' && retryCount < MAX_RETRIES) {
        console.log(`Retrying connection (attempt ${retryCount + 1} of ${MAX_RETRIES})...`);
        setTimeout(() => connect(retryCount + 1), RETRY_DELAY);
        return;
      }

      if (error.message === 'Failed to fetch') {
        setError('Network error. Please check your internet connection and try again.');
      } else {
        setError('Failed to connect wallet. Please try again.');
      }
      setIsConnecting(false);
    }
  }, [tonConnectUI]);

  const disconnect = useCallback(() => {
    tonConnectUI.disconnect();
  }, [tonConnectUI]);

  return {
    wallet,
    connect,
    disconnect,
    tonConnectUI,
    isConnecting,
    error,
  };
}

已完成的排查步骤 #

• 测试其他钱包：Tonkeeper等第三方钱包连接完全正常
• 跨小程序测试：在其他使用同一库的Telegram小程序中测试，问题复现
• 日志调试：添加日志追踪流程，控制台输出「Wallet connected successfully」但wallet状态未更新
• 重试机制：针对「Failed to fetch」错误实现重试逻辑，问题无改善

环境信息 #

• React/Next.js
• @tonconnect/ui-react库
• Telegram Mini-App 运行环境

问题分析与解决思路 #

1. Telegram小程序环境的特殊机制影响 #

Telegram Mini-App的WebView环境存在通信限制：

• PostMessage时序问题：Telegram内置钱包通过window.Telegram.WebApp桥接层通信，@tonconnect/ui-react默认的状态监听逻辑可能未适配这种异步通信的时序，导致连接成功的回调未触发。
• 状态同步差异：内置钱包的连接状态不会自动同步到tonConnectUI的状态池，需要主动触发拉取。

2. Telegram钱包与tonconnect/ui-react的集成适配问题 #

目前@tonconnect/ui-react对Telegram内置钱包的支持存在适配缺口：

• 连接成功后onStatusChange回调未被正确触发，导致wallet状态无法更新。
• 内置钱包的协议实现与标准TON Connect 2.0存在细微差异，库的默认逻辑未覆盖该场景。

3. 针对Telegram钱包的特殊配置 #

尝试以下适配配置：

• 主动拉取连接状态：在connectWallet调用完成后，手动拉取最新状态并更新wallet：

  await tonConnectUI.connectWallet();
  const latestWalletInfo = await tonConnectUI.getWalletInfo();
  setWallet(latestWalletInfo);
  

• 自定义钱包清单：初始化TonConnectUIProvider时，指定Telegram钱包的专属参数，确保库能正确识别：

  <TonConnectUIProvider
    manifestUrl="https://your-app.com/tonconnect-manifest.json"
    walletsList={[
      {
        appName: 'Telegram Wallet',
        name: 'Telegram Wallet',
        imageUrl: 'https://your-image-url.com',
        tgApp: 'telegram',
        universalLink: 'https://t.me/your_bot?start=tonconnect',
        deepLink: 'tg://resolve?domain=your_bot&start=tonconnect',
        bridgeUrl: 'https://bridge.tonapi.io/bridge'
      }
    ]}
  >
    {/* 你的应用组件 */}
  </TonConnectUIProvider>
  

4. CORS与应用内连接排查 #

Telegram WebView对CORS有严格限制，需确保：

• 你的TON Connect清单文件（tonconnect-manifest.json）所在域名配置了正确的CORS头，允许Telegram WebView访问。
• 使用官方推荐的TON Connect桥接地址（https://bridge.tonapi.io/bridge），避免自定义桥接的跨域问题。

额外调试建议 #

• 直接监听Telegram内置钱包的原生事件，查看连接数据：

  if (window.Telegram?.WebApp) {
    window.Telegram.WebApp.onEvent('wallet_connected', (data) => {
      console.log('Telegram wallet connected raw data:', data);
    });
  }
  

• 直接读取tonConnectUI.status获取当前连接状态，不依赖onStatusChange回调：

  console.log('Current tonConnect status:', tonConnectUI.status);
  

内容的提问来源于stack exchange，提问作者isofttechn