Web3 前端

概述

Web3 前端是去中心化应用（DApp）的用户界面层，它与传统 Web 应用最大的区别在于：用户通过加密钱包（如 MetaMask）持有自己的身份和资产，前端直接与区块链智能合约交互，而非依赖中心化后端服务器。Web3 前端的技术栈围绕以太坊生态展开，核心工具包括 Ethers.js、Wagmi、Viem 等库。本文将从工具链、合约交互、钱包连接、DApp 架构、IPFS 集成和安全实践等多个维度进行全面介绍。

---

Ethers.js

Ethers.js 是一个轻量级的以太坊 JavaScript 库，设计目标是"紧凑且完整"。它涵盖了与以太坊区块链交互所需的全部功能，是目前 Web3 前端开发中使用最广泛的库之一。

Provider

Provider 是以太坊网络的抽象连接，它提供对区块链状态的只读访问。Ethers.js 支持多种 Provider：

• JsonRpcProvider：通过 JSON-RPC 端点连接，例如 Infura、Alchemy 或本地节点
• WebSocketProvider：使用 WebSocket 实现实时数据推送
• Web3Provider：包装浏览器注入的以太坊 Provider（如 MetaMask 的 window.ethereum）
• FallbackProvider：组合多个 Provider，实现高可用性和请求负载均衡

import { ethers } from 'ethers';

// 通过 RPC 连接
const provider = new ethers.JsonRpcProvider('https://mainnet.infura.io/v3/YOUR_KEY');

// 包装浏览器钱包
const browserProvider = new ethers.BrowserProvider(window.ethereum);

Provider 提供的方法涵盖区块查询、交易状态、余额检查等基础功能，是所有读取操作的基础。

Signer

Signer 是能够签署交易的抽象，代表一个以太坊账户。Signer 既可以读取链上数据，也可以写入数据（发送交易）。最常见的 Signer 通过浏览器钱包获得：

const signer = await browserProvider.getSigner();
const address = await signer.getAddress();

Signer 与 Provider 的关键区别在于：Signer 持有私钥（或对私钥的访问权限），因此可以签署消息和交易；Provider 仅能读取公开数据。

Contract

Contract 对象封装了智能合约的 ABI 和地址，提供类型安全的方法调用接口：

const abi = [
  'function balanceOf(address owner) view returns (uint256)',
  'function transfer(address to, uint amount) returns (bool)'
];
const contract = new ethers.Contract(contractAddress, abi, signer);

// 读取
const balance = await contract.balanceOf(address);

// 写入（发送交易）
const tx = await contract.transfer(recipient, amount);
await tx.wait();

Contract 对象自动将 JavaScript 类型转换为 Solidity 类型，处理编码和解码细节。当使用 Provider（而非 Signer）实例化时，只能进行只读调用。

ABI

ABI（Application Binary Interface）是智能合约的接口描述，它以 JSON 数组形式定义合约的函数签名、参数类型和返回值类型。ABI 是 Ethers.js 编码/解码交易数据的依据。

ABI 条目包含以下关键字段：

• type：function、event、constructor、fallback、receive
• name：函数或事件名称
• inputs：输入参数数组，每个参数包含 name、type 和可选的 components（元组类型）
• outputs：返回值数组
• stateMutability：pure、view、nonpayable、payable

生成 ABI 的方式包括：从 Solidity 编译器输出中提取、使用 TypeChain 自动生成 TypeScript 类型、从 Etherscan 等区块浏览器下载已验证的合约 ABI。

交易

使用 Ethers.js 发起交易有两种方式：通过 Contract 对象的方法调用，或直接使用 Signer 发送原始交易。

// 方式一：通过 Contract
const tx = await contract.transfer(recipient, amount);
const receipt = await tx.wait();

// 方式二：发送原始交易
const txResponse = await signer.sendTransaction({
  to: recipient,
  value: ethers.parseEther('0.1'),
  data: '0x...'  // 可选，如果只是转账 ETH 则不需要
});

tx.wait() 返回交易收据（TransactionReceipt），其中包含区块号、Gas 使用量、日志（事件）等关键信息。

事件监听

Ethers.js 支持实时监听链上事件，这对于需要及时更新 UI 的 DApp 至关重要：

// 监听合约事件
contract.on('Transfer', (from, to, value, event) => {
  console.log(`Transfer: ${from} -> ${to}, value: ${value}`);
});

// 一次性监听
contract.once('Transfer', (from, to, value) => {
  console.log('首次转账事件');
});

// 按过滤器监听
const filter = contract.filters.Transfer(myAddress);
contract.on(filter, (from, to, value) => {
  // 只监听与 myAddress 相关的转账
});

// 取消监听
contract.removeAllListeners('Transfer');

事件监听基于 WebSocket 或长轮询实现。对于高频事件，建议使用 WebSocket Provider 以获得最佳实时性。

ENS

以太坊名称服务（ENS）将人类可读的名称（如 vitalik.eth）映射到以太坊地址。Ethers.js 原生支持 ENS 解析：

// 名称解析为地址
const address = await provider.resolveName('vitalik.eth');

// 地址反向解析为名称
const name = await provider.lookupAddress('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045');

ENS 支持还扩展到合约地址、内容哈希、文本记录等多种解析类型，是 DApp 用户体验的重要组成部分。

Ethers.js 与 Web3.js 对比

特性	Ethers.js	Web3.js
包体积	较小（约 200KB gzipped）	较大（约 400KB+ gzipped）
TypeScript 支持	原生支持，类型完备	社区类型，支持较弱
ENS 解析	内置支持	需要额外配置
Provider/Signer 分离	清晰的职责分离	概念混合
API 设计	更现代，使用 Promise	回调与 Promise 混用
传输层	内置多种 Provider	依赖 HTTP 提供者
文档质量	文档良好，示例丰富	文档较历史，示例分散
Gas 估算	自动处理	需要手动设置
事件过滤	语法简洁	配置较复杂
社区活跃度	增长迅速	成熟但增长放缓

整体而言，新项目推荐使用 Ethers.js 或更现代的 Viem 库。Web3.js 的主要优势在于其长期存在带来的生态兼容性和大量遗留项目。

---

Wagmi

Wagmi 是一个专为 React 应用设计的以太坊 Hooks 库，它基于 Viem 构建，提供了声明式的链交互方式。Wagmi 极大地简化了 Web3 React 应用的开发。

React Hooks

Wagmi 提供了一系列 React Hooks，涵盖 Web3 开发的常见场景：

import { useAccount, useBalance, useBlockNumber } from 'wagmi';

function WalletInfo() {
  const { address, isConnected } = useAccount();
  const { data: balance } = useBalance({ address });
  const { data: blockNumber } = useBlockNumber();

  if (!isConnected) return <p>请连接钱包</p>;
  return (
    <div>
      <p>地址: {address}</p>
      <p>余额: {balance?.formatted} ETH</p>
      <p>当前区块: {blockNumber}</p>
    </div>
  );
}

其他常用 Hooks 包括 useReadContract、useWriteContract、useSendTransaction、useSignMessage、useSwitchChain、useConnect、useDisconnect 等，覆盖了从读取数据到签署消息的全链路。

连接管理

Wagmi 通过 Connector 抽象管理不同的钱包连接方式。Connector 支持 MetaMask、WalletConnect、Coinbase Wallet 等：

import { useConnect, useDisconnect } from 'wagmi';
import { metaMask, walletConnect, coinbaseWallet } from 'wagmi/connectors';

function WalletConnector() {
  const { connect, connectors, isLoading, error } = useConnect();

  return (
    <div>
      {connectors.map((connector) => (
        <button key={connector.id} onClick={() => connect({ connector })}>
          {connector.name}
          {isLoading && '...'}
        </button>
      ))}
    </div>
  );
}

Wagmi 自动管理连接状态的生命周期，包括连接建立、断开、账户切换和链切换等。

链切换

Wagmi 提供了简洁的链切换 API，用户可以通过 useSwitchChain Hook 在不同的区块链网络之间切换：

import { useSwitchChain, useChainId } from 'wagmi';

function NetworkSwitcher() {
  const chainId = useChainId();
  const { switchChain, isPending } = useSwitchChain();

  return (
    <select
      value={chainId}
      onChange={(e) => switchChain({ chainId: Number(e.target.value) })}
      disabled={isPending}
    >
      <option value={1}>Ethereum Mainnet</option>
      <option value={137}>Polygon</option>
      <option value={42161}>Arbitrum</option>
      <option value={10}>Optimism</option>
    </select>
  );
}

Wagmi 的链配置通过 createConfig 定义，支持 RPC URL、区块浏览器和合约地址等元数据。

合约读写

Wagmi 的 useReadContract 和 useWriteContract 是合约交互的核心 Hooks：

import { useReadContract, useWriteContract } from 'wagmi';
import { abi } from './nft-abi';

function NFTBalance({ address, contractAddress }) {
  const { data: balance, isLoading } = useReadContract({
    address: contractAddress,
    abi,
    functionName: 'balanceOf',
    args: [address],
  });

  return <p>持有数量: {balance?.toString()}</p>;
}

function TransferButton() {
  const { writeContract, isPending } = useWriteContract();

  const handleTransfer = () => {
    writeContract({
      address: contractAddress,
      abi,
      functionName: 'transfer',
      args: [recipient, amount],
    });
  };

  return <button onClick={handleTransfer} disabled={isPending}>转账</button>;
}

写入操作返回交易哈希，可以使用 useWaitForTransactionReceipt 等待交易确认。

签名

Wagmi 支持消息签名和 typed data 签名：

import { useSignMessage, useSignTypedData } from 'wagmi';

function SignMessage() {
  const { signMessage, data, isPending } = useSignMessage();

  return (
    <div>
      <button onClick={() => signMessage({ message: 'Hello Web3' })}>
        签名消息
      </button>
      {data && <p>签名: {data}</p>}
    </div>
  );
}

签名功能是实现 Sign-In with Ethereum（SIWE）、链下身份验证和授权的基础。

自动刷新

Wagmi 具有内建的自动刷新机制。当链状态变化（如区块更新、账户切换、链切换）时，相关的数据查询会自动失效并重新获取。这得益于其底层对 Viem 和 TanStack Query 的集成，开发者无需手动管理缓存失效逻辑。

与 Ethers 集成

虽然 Wagmi 基于 Viem，但可以通过以下方式与 Ethers.js 集成：

import { useWalletClient } from 'wagmi';
import { ethers } from 'ethers';

function WalletInfo() {
  const { data: walletClient } = useWalletClient();

  const connectToEthers = async () => {
    if (walletClient) {
      // 将 WalletClient 转换为 Ethers Signer
      const provider = new ethers.BrowserProvider(
        walletClient.transport,
        'any'
      );
      const signer = await provider.getSigner();
      // 使用 signer 与 Ethers 生态工具交互
    }
  };
}

这种方式允许项目在享受 Wagmi 状态管理优势的同时，利用 Ethers.js 中某些 Wagmi/Viem 尚未覆盖的特定功能。

---

智能合约交互

智能合约交互是 Web3 前端的核心功能，涉及从 ABI 编码到交易发起的完整链路。

ABI 编码与解码

合约调用最终需要转换为区块链虚拟机可理解的二进制格式。Ethers.js 提供了底层的编码/解码接口：

import { ethers } from 'ethers';

// 函数编码
const iface = new ethers.Interface(abi);
const encodedData = iface.encodeFunctionData('transfer', [
  recipient,
  ethers.parseEther('1.0')
]);

// 结果解码
const result = iface.decodeFunctionResult('balanceOf', returnData);

v4.0 版本以后的 Ethers.js 还提供了 AbiCoder 用于底层类型编码。

交易发起

完整的交易流程包括交易构建、Gas 估算、签名、广播和确认：

const txRequest = {
  to: contractAddress,
  data: encodedData,
  value: 0n,
};

// Gas 估算
const gasEstimate = await provider.estimateGas(txRequest);
// Gas 价格
const feeData = await provider.getFeeData();

// 发送交易
const tx = await signer.sendTransaction({
  ...txRequest,
  gasLimit: gasEstimate * 120n / 100n,  // 增加 20% buffer
  maxFeePerGas: feeData.maxFeePerGas,
  maxPriorityFeePerGas: feeData.maxPriorityFeePerGas,
});

// 等待确认
const receipt = await tx.wait();

交易确认后，收据中的 status 字段指示交易是否成功（1 表示成功）。

Gas 策略

Gas 管理对用户体验和交易成功率至关重要：

• EIP-1559 交易：使用 maxFeePerGas 和 maxPriorityFeePerGas，由网络自动计算基础费用
• Gas 限制：建议在估计值基础上增加 10-20% 的 buffer，防止复杂合约调用因 Gas 不足而失败
• Gas 价格策略：对于非紧急交易，可以使用稍低的价格以节省成本；紧急交易则使用较高的优先费用
• 取消/加速交易：通过发送相同 nonce 的交易来覆盖待处理的交易

事件监听高级用法

除了基础的事件监听，还可以使用日志过滤器实现精确的数据订阅：

// 创建事件过滤器
const filter = {
  address: contractAddress,
  topics: [
    ethers.id('Transfer(address,address,uint256)'),
    null,  // 不限制 from
    ethers.hexZeroPad(ethers.getAddress(myAddress), 32),  // 只监听 to 为 myAddress
  ],
};

provider.on(filter, (log) => {
  const parsedLog = iface.parseLog(log);
  console.log('过滤后的事件:', parsedLog.args);
});

对于历史事件查询，使用 getLogs 方法配合区块范围参数。

合约验证

合约验证是 DApp 透明度和安全性的重要环节。前端可以集成 Etherscan API，允许用户直接查看已验证的合约源码：

// 链接到 Etherscan 已验证合约
const etherscanUrl = `https://etherscan.io/address/${contractAddress}#code`;

// 通过 Etherscan API 获取 ABI
const response = await fetch(
  `https://api.etherscan.io/api?module=contract&action=getabi&address=${contractAddress}&apikey=${apiKey}`
);
const abi = JSON.parse((await response.json()).result);

验证状态应在前端 UI 中明确展示，帮助用户确认他们交互的合约是经过审查的。

Multicall

Multicall 技术允许在单个 RPC 调用中执行多个独立的合约读取操作，大幅提升数据加载效率：

import { ethers } from 'ethers';
import { MulticallWrapper } from 'ethers-multicall-provider';

const multicallProvider = MulticallWrapper.wrap(provider);
const multicallContract = new ethers.Contract(address, abi, multicallProvider);

// 批量读取
const [balance, totalSupply, name, symbol] = await Promise.all([
  multicallContract.balanceOf(user),
  multicallContract.totalSupply(),
  multicallContract.name(),
  multicallContract.symbol(),
]);

使用 Multicall 可以将多次 RPC 请求合并为一次，特别适合 NFT 市场、DeFi 仪表盘等需要展示大量链上数据的场景。

---

钱包连接

钱包连接是用户进入 Web3 应用的门户，涉及多种钱包标准和连接协议。

MetaMask

MetaMask 是最广泛使用的浏览器扩展钱包。它通过 window.ethereum 对象注入到网页中：

// 检测 MetaMask
if (typeof window.ethereum !== 'undefined') {
  // 请求账户
  const accounts = await window.ethereum.request({
    method: 'eth_requestAccounts'
  });
  const account = accounts[0];
} else {
  // 提示用户安装 MetaMask
  window.open('https://metamask.io/download');
}

EIP-1193 标准定义了 window.ethereum 的 Provider 接口，使 DApp 能够以统一的方式与钱包通信。

WalletConnect

WalletConnect 是一个开放协议，允许 DApp 通过二维码扫码或深度链接与移动端钱包连接：

import WalletConnectProvider from '@walletconnect/web3-provider';

const provider = new WalletConnectProvider({
  projectId: 'YOUR_PROJECT_ID',
  chains: [1],  // Ethereum Mainnet
  rpc: {
    1: 'https://mainnet.infura.io/v3/YOUR_KEY',
  },
});

await provider.enable();

WalletConnect v2.0 引入了多链支持和改进的会话管理，是目前跨钱包连接的事实标准。

Coinbase Wallet

Coinbase Wallet 同时提供浏览器扩展和移动端钱包，使用 WalletConnect 协议或 Coinbase SDK 进行连接：

import { CoinbaseWalletSDK } from '@coinbase/wallet-sdk';

const sdk = new CoinbaseWalletSDK({
  appName: 'My DApp',
  appLogoUrl: 'https://example.com/logo.png',
});

const provider = sdk.makeWeb3Provider();
const accounts = await provider.request({ method: 'eth_requestAccounts' });

连接流程

标准钱包连接流程如下：

1. 检测 Provider：检查 window.ethereum 或加载 SDK
2. 请求连接：调用 eth_requestAccounts 或 enable() 方法
3. 用户授权：钱包弹出确认界面，用户选择账户并授权
4. 获取账户信息：读取地址、链 ID、余额等信息
5. 更新 UI 状态：显示连接状态和账户信息

ChainID 切换

DApp 需要确保用户连接在正确的链上。链切换流程包括：

const switchChain = async (targetChainId) => {
  try {
    await window.ethereum.request({
      method: 'wallet_switchEthereumChain',
      params: [{ chainId: '0x' + targetChainId.toString(16) }],
    });
  } catch (error) {
    // 链未添加到钱包，需要添加
    if (error.code === 4902) {
      await window.ethereum.request({
        method: 'wallet_addEthereumChain',
        params: [{
          chainId: '0x' + targetChainId.toString(16),
          chainName: 'Polygon Mainnet',
          nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
          rpcUrls: ['https://polygon-rpc.com'],
          blockExplorerUrls: ['https://polygonscan.com'],
        }],
      });
    }
  }
};

EIP-3085 和 EIP-3326 分别定义了添加和切换链的 RPC 方法。

账户切换监听

钱包账户切换是异步的，前端需要监听变化以保持 UI 同步：

if (window.ethereum) {
  // 账户切换
  window.ethereum.on('accountsChanged', (accounts) => {
    if (accounts.length === 0) {
      // 用户断开连接
      handleDisconnect();
    } else {
      // 账户已切换
      handleAccountChange(accounts[0]);
    }
  });

  // 链切换
  window.ethereum.on('chainChanged', (chainId) => {
    // 建议刷新页面或重新加载数据
    handleChainChange(parseInt(chainId, 16));
  });

  // 断开连接
  window.ethereum.on('disconnect', (error) => {
    handleDisconnect();
  });
}

---

DApp 开发

构建生产级 DApp 需要考虑前端架构、合约集成、签名认证、交易流程和 UI 设计等多个方面。

前端架构

典型的 Web3 DApp 前端架构包含以下层次：

UI 组件层 (React/Vue 组件)
    ↑
状态管理层 (Wagmi Hooks / Redux / Zustand)
    ↑
合约交互层 (Ethers.js / Viem)
    ↑
Provider 层 (RPC / WebSocket / 钱包 Provider)
    ↑
区块链网络 (Ethereum / L2 / Sidechain)

推荐的项目结构：

src/
├── components/       # 通用 UI 组件
├── hooks/           # 自定义 Web3 Hooks
├── contracts/       # ABI 和合约地址配置
├── providers/       # Wagmi 配置和 Provider 设置
├── utils/           # 工具函数（格式化、编码等）
├── pages/           # 页面组件
└── types/           # TypeScript 类型定义

合约集成

合约集成的最佳实践：

• 地址管理：将合约地址按网络环境配置，使用环境变量或配置文件管理
• ABI 管理：使用 TypeChain 从 ABI 生成类型安全的 TypeScript 绑定，避免硬编码 ABI
• 合约版本控制：使用升级代理模式时，将实现合约地址与代理地址分开管理
• 测试网部署：在 Goerli、Sepolia 等测试网上部署并验证合约后再发布主网版本

// 多网络合约配置示例
const contractConfig = {
  1: {         // Ethereum Mainnet
    address: '0x...',
    explorer: 'https://etherscan.io',
  },
  137: {       // Polygon
    address: '0x...',
    explorer: 'https://polygonscan.com',
  },
  80001: {     // Mumbai Testnet
    address: '0x...',
    explorer: 'https://mumbai.polygonscan.com',
  },
};

签名登录与 SIWE

Sign-In with Ethereum（EIP-4361）是以太坊登录的标准协议，允许用户使用钱包签名进行身份验证：

const siweMessage = new SiweMessage({
  domain: window.location.host,
  address: userAddress,
  statement: '签署此消息以登录 DApp',
  uri: window.location.origin,
  version: '1',
  chainId: chainId,
  nonce: await getNonce(),  // 从后端获取一次性 nonce
});

// 用户签名
const signature = await signer.signMessage(siweMessage.toMessage());

// 发送到后端验证
const response = await fetch('/api/verify', {
  method: 'POST',
  body: JSON.stringify({ message: siweMessage, signature }),
});

SIWE 流程中，后端负责验证签名有效性、检查 nonce 防止重放攻击，并签发会话 Token。

交易流程

完整的交易流程用户体验设计：

用户点击 "提交" 按钮
    ↓
加载中状态 (按钮禁用，显示 spinner)
    ↓
钱包弹出确认窗口 (用户确认交易)
    ↓
pending 状态 (等待上链，显示交易哈希)
    ↓
交易确认 (显示成功提示，更新 UI 数据)
    ↓
(可选) 等待更多确认 (提高安全性)
    ↓
完成

function TransactionButton() {
  const [status, setStatus] = useState('idle'); // idle | loading | pending | success | error
  const [txHash, setTxHash] = useState('');

  const handleSubmit = async () => {
    setStatus('loading');
    try {
      const tx = await contract.mint();
      setTxHash(tx.hash);
      setStatus('pending');

      const receipt = await tx.wait();
      setStatus('success');
      // 刷新数据
    } catch (error) {
      setStatus('error');
      console.error(error);
    }
  };

  // 根据 status 渲染不同的 UI
}

UI 最佳实践

Web3 DApp 的 UI 设计需要考虑以下方面：

• 交易状态可视化：清晰展示 idle、loading、pending、success、error 五个状态
• Gas 费用预览：在用户确认交易前显示预估 Gas 费用
• 链上数据加载骨架屏：使用骨架屏避免布局抖动
• 错误处理友好化：将底层错误（如 "execution reverted"）转换为用户可理解的消息
• 响应式设计：适配桌面和移动端，特别是移动端钱包连接体验
• 交易历史：显示用户的历史交易记录和状态
• 重试机制：交易失败时提供一键重试

---

IPFS

星际文件系统（IPFS）是 Web3 存储的核心基础设施，通过内容寻址实现去中心化的文件存储和分发。

文件上传与内容寻址

IPFS 将文件内容通过哈希运算生成唯一的 CID（Content Identifier），内容寻址意味着相同的文件总是产生相同的 CID：

import { create } from 'ipfs-http-client';

const ipfs = create({ url: 'https://ipfs.infura.io:5001' });

const uploadFile = async (file) => {
  const result = await ipfs.add(file);
  // result.path 是 CID
  // result.size 是文件大小
  return `https://ipfs.io/ipfs/${result.path}`;
};

IPFS URL 可以通过多个公共网关访问，包括 ipfs.io、cloudflare-ipfs.com、gateway.pinata.cloud 等。

Pinata

Pinata 是一个 IPFS 固定服务，提供文件上传、固定（Pinning）和管理的 API。固定（Pinning）确保文件在 IPFS 网络上持续可用：

const pinFileToIPFS = async (file) => {
  const formData = new FormData();
  formData.append('file', file);

  const response = await fetch('https://api.pinata.cloud/pinning/pinFileToIPFS', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${PINATA_JWT}`,
    },
    body: formData,
  });

  const data = await response.json();
  return `https://gateway.pinata.cloud/ipfs/${data.IpfsHash}`;
};

Pinata 还支持 JSON 数据固定，非常适合存储 NFT 元数据：

const pinJSONToIPFS = async (metadata) => {
  const response = await fetch('https://api.pinata.cloud/pinning/pinJSONToIPFS', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${PINATA_JWT}`,
    },
    body: JSON.stringify(metadata),
  });

  return await response.json();
};

Web3.Storage

Web3.Storage 是一个免费的去中心化存储服务，将文件同时存储在 IPFS 和 Filecoin 上。它提供 JavaScript 客户端库，使用简单：

import { Web3Storage } from 'web3.storage';

const storage = new Web3Storage({ token: WEB3_STORAGE_TOKEN });

const uploadToWeb3Storage = async (files) => {
  const cid = await storage.put(files);
  return `https://${cid}.ipfs.w3s.link`;
};

// 上传文件列表
const files = [imageFile, metadataFile];
const url = await uploadToWeb3Storage(files);

Web3.Storage 的优势在于它通过 Filecoin 网络提供了持久化存储保证，文件在存储期限内不会丢失。

结合 NFT

NFT 元数据（图片、描述、属性等）通常存储在 IPFS 上，合约中只存储元数据的 URI：

// NFT 元数据结构
const nftMetadata = {
  name: 'CyberPunk #0420',
  description: '一件稀有的赛博朋克风格数字艺术品',
  image: 'ipfs://QmX...',  // 图片的 IPFS CID
  attributes: [
    { trait_type: '背景', value: '霓虹紫' },
    { trait_type: '稀有度', value: '传说' },
    { trait_type: '能量值', value: 100 },
  ],
};

// 上传元数据到 IPFS
const metadataCID = await pinJSONToIPFS(nftMetadata);

// 在合约中使用
contract.safeMint(recipient, `ipfs://${metadataCID}`);

标准 NFT 元数据遵循 OpenSea 的元数据规范，确保市场平台能够正确解析和展示。

---

Web3 安全

Web3 前端安全与传统 Web 安全有显著差异，核心关注点从后端数据传输转向客户端-钱包交互的安全。

前端安全

Web3 前端的主要安全风险包括：

• 恶意 RPC 端点：使用不可信的 RPC 节点可能导致交易被篡改或数据被伪造
• 供应链攻击：Web3 依赖大量 npm 包，恶意包可能窃取私钥或修改交易
• XSS 攻击：在 DApp 中注入恶意脚本，伪造钱包交互弹窗
• 虚假审批：诱导用户签署恶意合约的 approve 交易

安全措施：

// 1. 内容安全策略
// 在 HTML 中设置：
// <meta http-equiv="Content-Security-Policy" content="default-src 'self'; connect-src 'self' https://*.infura.io">

// 2. 使用受信任的 RPC 端点
const trustedRpcs = {
  1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
  137: 'https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY',
};
const provider = new ethers.JsonRpcProvider(trustedRpcs[chainId]);

// 3. 验证交易参数
const validateTransfer = (to, amount) => {
  if (!ethers.isAddress(to)) throw new Error('无效地址');
  if (amount <= 0) throw new Error('金额必须大于 0');
  if (amount > maxAllowed) throw new Error('金额超出限制');
};

签名验证

前端必须验证所有链下签名数据的完整性和来源：

const verifySignature = async (message, signature, expectedSigner) => {
  try {
    const recoveredAddress = ethers.verifyMessage(message, signature);
    return recoveredAddress.toLowerCase() === expectedSigner.toLowerCase();
  } catch {
    return false;
  }
};

// Typed Data 签名验证
const verifyTypedData = (domain, types, value, signature, expectedSigner) => {
  const recovered = ethers.verifyTypedData(domain, types, value, signature);
  return recovered.toLowerCase() === expectedSigner.toLowerCase();
};

对于 SIWE 登录，验证逻辑应在后端执行，前端只负责展示签名请求和发送结果。

钓鱼防护

钓鱼攻击是 Web3 用户面临的最大威胁之一。前端开发者的责任：

• 清晰的交易预览：在钱包确认前，在 DApp UI 中显示完整的交易详情（目标合约、方法、参数值、Gas 费用）
• 合约地址白名单：维护经过验证的合约地址列表，与交易目标地址进行比对
• 域名验证：检查 window.location.host 是否匹配预期域名，防止 DNS 劫持
• 安全提示：提醒用户检查钱包弹窗中的链 ID 和 Gas 费用

const TransactionPreview = ({ tx }) => (
  <div class="tx-preview">
    <h3>交易预览</h3>
    <div>合约: {shortenAddress(tx.to)}</div>
    <div>方法: {tx.functionName}</div>
    <div>参数: {JSON.stringify(tx.args)}</div>
    <div>Gas 费用: ~{formatEther(tx.gasEstimate * tx.gasPrice)} ETH</div>
    <div class="warning">
      请在钱包弹窗中确认以上信息与 DApp 显示一致
    </div>
  </div>
);

RPC 端点安全

RPC 端点是 DApp 与区块链通信的桥梁，其安全性直接影响应用的可信度：

• 优先使用自建节点或知名服务商（Infura、Alchemy、QuickNode）
• 对 RPC 请求实施速率限制，防止滥用
• 使用 HTTPS 加密所有 RPC 通信
• 为不同环境（开发/测试/生产）使用独立的 API Key
• 考虑使用去中心化 RPC 网络（如 Pocket Network）避免单点故障

私钥管理

前端开发中最重要的安全原则是：永远不接触用户的私钥。浏览器的 JavaScript 环境不应直接管理密钥：

• 使用硬件钱包：Ledger、Trezor 等硬件钱包确保私钥离线存储
• 使用浏览器扩展钱包：MetaMask、Rabby 等将密钥隔离在安全沙箱中
• 使用 MPC 钱包：多方计算钱包将密钥分片，任何一方都无法单独控制资产
• 避免私钥输入：DApp 不应提供私钥或助记词输入框，这是高风险的反模式

如果必须进行服务端签名（如中继器），应使用专用的签名服务，私钥存储在硬件安全模块（HSM）或密钥管理服务（KMS）中。

---

总结

Web3 前端开发是一个融合了传统前端工程化与区块链技术的新兴领域。Ethers.js 提供了底层链交互能力，Wagmi 将这种能力封装为声明式的 React Hooks，钱包连接协议（MetaMask、WalletConnect）为用户提供统一的身份入口，IPFS 解决了去中心化存储问题，而安全实践则是保护用户资产的最后防线。

随着以太坊 L2 生态的成熟和账户抽象（ERC-4337）的推广，Web3 前端的开发体验将进一步提升。推荐开发者在实际项目中结合实际需求选择合适的工具链，并始终将安全性和用户体验放在首位。

---

Demo