基于 NEAR Wallet Selector 集成以太坊钱包全流程指南

你是否想让 NEAR DApp 也像传统 Web3 项目一样，一键连接 MetaMask、WalletConnect 等 以太坊钱包？借助新区块链互操作协议，开发者现在可以在 30 分钟内把 EVM 钱包接入 NEAR 应用，无需复杂桥接或额外助记词。本文将带你完成从升级包版本到上线可用的全部步骤，并穿插实战代码、配置示例与常见问题解答。

目录速览

升级 Wallet Selector 与安装 Web3Modal
配置 NEAR 链信息与 RPC 节点
创建 Web3Modal 并绑定到 Wallet Selector
初始化并测试 ethereum-wallets 模块
实战部署与验证
进阶 FAQ

Step 1：一次性升级所有依赖包

1.1 Wallet Selector 核心包

打开 package.json，将 Wallet Selector 统一升级到 8.9.13 及以上，并加入以太坊插件：

"dependencies": {
  "@near-wallet-selector/core": "^8.9.13",
  "@near-wallet-selector/ethereum-wallets": "^8.9.13",
  "@near-wallet-selector/here-wallet": "^8.9.13",
  "@near-wallet-selector/modal-ui": "^8.9.13",
  "@near-wallet-selector/my-near-wallet": "^8.9.13"
}

1.2 引入 Web3Modal 及其生态

Web3Modal（也称 Reown AppKit）是目前 以太坊生态主流多钱包连接器，支持 React、Vue、纯前端等框架。下面以 React 为例：

npm install @web3modal/wagmi wagmi viem @tanstack/react-query

安装后，后续所有 EVM 钱包接入均通过 @web3modal/wagmi 提供的 useConnect、useAccount 等 Hooks 完成。

Step 2：配置 NEAR 专属链信息

不同于一般的 EVM 链，NEAR 通过 Aurora Engine 提供 EVM 兼容执行层。我们需要把 RPC、ChainId、浏览器地址写进 wagmi 的 chain 配置：

import { defineChain } from 'viem';

const nearAurora = defineChain({
  id: 1313161554,          // Aurora Mainnet ChainId
  name: 'NEAR Aurora',
  network: 'aurora',
  nativeCurrency: { name: 'ETH', symbol: 'ETH', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://mainnet.aurora.dev'] }
  },
  blockExplorers: {
    default: { name: 'Aurora Explorer', url: 'https://explorer.aurora.dev' }
  }
});

要点：

ChainId 必须匹配 NEAR Aurora 官方文档
rpcUrls 可以替换为自建节点，提升稳定性

Step 3：新建 Web3Modal 入口文件

3.1 获取 Reown 项目 ID（projectId）

打开 Cloud Reown
注册并创建项目
复制生成的 projectId

小技巧：使用 GitHub OAuth 可一键登录，省去邮箱验证。

3.2 创建 wagmi 配置

在项目根目录新建 src/wallets/web3modal.ts：

import { createConfig, http } from 'wagmi';
import { nearAurora } from './chains';
import { reconnect } from '@wagmi/core';

export const wagmiConfig = createConfig({
  chains: [nearAurora],
  transports: {
    [nearAurora.id]: http()
  },
  ssr: true
});

// ⚠️ 刷新页面后保持连接
reconnect(wagmiConfig);

3.3 创建 Web3Modal 实例

import { createWeb3Modal } from '@web3modal/wagmi/react';
import { wagmiConfig } from './wagmi';

export const web3Modal = createWeb3Modal({
  wagmiConfig,
  projectId: import.meta.env.VITE_REOWN_PROJECT_ID,
  enableAnalytics: true // 可选，统计连接来源
});

这样，即可在点击 NEAR Wallet Selector 时无缝唤起 MetaMask、Rainbow、Coinbase Wallet 等所有 EVM 钱包。

Step 4：把 EVM 钱包塞进 Wallet Selector

打开入口组件或登陆页的 setupWalletSelector 调用，额外添加 setupEthereumWallets：

import { setupWalletSelector } from '@near-wallet-selector/core';
import { setupEthereumWallets } from '@near-wallet-selector/ethereum-wallets';
import { wagmiConfig, web3Modal } from '@/wallets/web3modal';

const selector = await setupWalletSelector({
  network: 'mainnet',
  modules: [
    setupEthereumWallets({
      wagmiConfig,
      web3Modal
    })
    // 此处继续保留 NEAR 原生钱包模块
  ]
});

👆 一次搞定多链登录，再也不用维护两套钱包逻辑！

Step 5：运行、测试与上线

5.1 本地热更新

npm run dev

点击登录时，应在 NEAR Wallet Selector 弹窗看到新增「Ethereum Wallets」按钮；选择后自动弹出 Web3Modal，确认连接签名即可。

5.2 线上验证

部署后可以到 NEAR 区块浏览器查询合约调用或查看交易回执。若出现签名失败，优先检查以下内容：

ChainId 是否正确
projectId 是否在环境变量里正确读取
Aurora RPC 健康状态（ Busy → 换成备用节点）

进阶 FAQ

Q1：NEAR 主网与测试网的 ChainId 分别是多少？

主网：1313161554（Aurora）
测试网：1313161555
切换网络时只需修改 defineChain 里的 id 和 RPC 即可。

Q2：支持非 React 框架吗？

可以。@web3modal/html 支持纯 DOM；@web3modal/vue 支持 Vue 技术栈。配置思路相同。

Q3：效率如何？会不会导致高 Gas？

交互本身走的是 Aurora EVM 层，Gas ≈ 常规 Polygon / Optimism 水平，通常在 0.003 ~ 0.05 USD，用户基本无感。

Q4：如果出现「Unsupported chain」错误怎么办？

通常是钱包默认锁定在以太坊主网，用户需要：

在钱包内 手动添加 Aurora 网络
或使用代码强制切换（wallet_switchEthereumChain）

Q5：旧版 Wallet Selector 必须升级到 8.9.13 吗？

强烈建议。8.9.13 以下版本缺少 ethereum-wallets 适配器，会导致无法识别 Web3Modal。

Q6：可以把 EVM 钱包地址映射到 NEAR 账户吗？

通过 NEAR NEP-518 协议，用户第一次签名即生成 implicit EVM account，其地址与 NEAR AccountId 自动绑定，开发者无需手动管理。

小结与下一步

完成上文 5 步之后，你的 NEAR DApp 已具备 原生级别 的以太坊钱包接入能力。下一步可以考虑：

个性化 Web3Modal 主题色，与品牌色一致
引入 交易风控 API，降低钓鱼签名风险
把钱包连接逻辑封装成 SDK / Hooks，在多个产品间共享

👉 深入了解多链生态的下一站玩法

祝大家开发顺利，钱包体验越来越顺畅！

关键词：NEAR Wallet Selector、以太坊钱包集成、EVM 钱包支持、Web3Modal、Aurora RPC、NEP-518、MetaMask 连接 NEAR、React 前端区块链