React项目deeplinking连接MetaMask后无法跳转回原URL问题

问题根因 #

MetaMask移动端的deeplink授权流程要求必须明确传入DApp的访问地址，未按官方规范构造deeplink的情况下，授权完成后MetaMask无法获知回跳目标地址，就会停留在钱包应用内，不会自动返回原网页。

修复步骤 #

• 移除原有自定义的deeplink唤起逻辑，统一使用MetaMask官方推荐的通用链接格式构造唤起地址，该格式会自动处理回跳逻辑，授权完成后自动拉起浏览器回到原页面。
• 构造deeplink时不要硬编码页面地址，直接取当前页面的window.location.href做动态拼接，适配测试、生产所有部署环境。
• 修正移动端环境判断逻辑，区分「已经在MetaMask内置浏览器打开」和「在普通移动端浏览器打开」两种场景，前者直接请求授权，后者再走deeplink唤起流程。

修正后可直接复用的代码 #

// 移动端环境判断：识别移动端普通浏览器（非MetaMask内置环境）
const mobileCheck = () => {
  const ua = navigator.userAgent.toLowerCase();
  const isMobile = /iphone|ipad|ipod|android/.test(ua);
  const isInMetaMaskBrowser = window.ethereum?.isMetaMask === true;
  return isMobile && !isInMetaMaskBrowser;
};

// 钱包连接逻辑
const connect = async () => {
  try {
    // 非移动端/已在MetaMask内置浏览器，直接发起授权请求
    if (!mobileCheck()) {
      if (!window.ethereum) throw new Error("请先安装MetaMask钱包");
      const accounts = await window.ethereum.request({
        method: "eth_requestAccounts"
      });
      accountChangeHandler(accounts[0]);
      return;
    }
    // 移动端普通浏览器：构造符合规范的MetaMask deeplink
    const currentPageUrl = window.location.href;
    // 拼接deeplink，移除url开头的http/https前缀避免解析错误
    const deepLink = `https://metamask.app.link/dapp/${currentPageUrl.replace(/^https?:\/\//, '')}`;
    // 跳转到deeplink唤起MetaMask
    window.location.href = deepLink;
  } catch (err) {
    console.error("钱包连接异常：", err);
  }
};

// 原有连接状态检测逻辑微调
async function checkIfWalletIsConnected() {
  if (window.ethereum) {
    const accounts = await window.ethereum.request({
      method: "eth_accounts",
    });

    if (accounts.length > 0) {
      const account = accounts[0];
      accountChangeHandler(account);
      return;
    }
  }
  // 移动端环境直接触发连接流程
  if (mobileCheck()) {
    await connect();
  }
}

// 页面加载时执行状态检测
window.addEventListener('load', checkIfWalletIsConnected);

避坑说明 #

以下问题会直接导致回跳失败，需要逐一排查：

1. 不要使用metamask://开头的私有协议schema直接唤起钱包，不同版本MetaMask对私有协议的兼容性差，官方已经明确推荐使用通用链接格式
2. 拼接deeplink时，DApp地址必须去掉开头的http://或https://，否则会出现路径解析错误，无法正常回跳
3. 本地开发环境（比如localhost、127.0.0.1开头的本地地址）同样适配该逻辑，不需要额外做特殊处理
4. 授权完成回跳后页面会重新加载，原有checkIfWalletIsConnected逻辑会自动执行拉取已授权地址，不需要额外做本地状态持久化

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