使用 Vite 创建一个 React 项目 推荐)

Web3包导入工程：从零开始的完整指南

---

随着区块链技术的普及,Web3 开发已成为许多开发者的新战场，无论是与智能合约交互、构建去中心化应用（DApp），还是处理加密货币交易，Web3 包都是不可或缺的工具，对于初学者而言，“如何将 Web3 包成功导入工程”可能是一个令人困惑的第一步，本文将以最流行的 JavaScript/TypeScript 生态为例，手把手带你完成 Web3 包的导入与配置，并介绍其他主流语言的实现方法。

---

第一步：选择你的 Web3 包

在开始之前,你需要根据你的项目需求选择合适的 Web3 库，目前市面上最主流的选择是：

1. ethers.js：一个轻量级、模块化的 JavaScript 库，以其清晰的 API 设计和出色的文档而闻名，它非常适合与以太坊生态系统（包括 EVM 兼容链）进行交互，是目前社区的首选之一。
2. web3.js：这是最早也是最成熟的以太坊 JavaScript API 库，功能强大，但相比 ethers.js，其 API 设计略显复杂，体积也更大。
3. viem：一个新兴的、由 TypeScript 驱动的轻量级库，旨在成为 ethers.js 的现代化替代品，它以极简的 API 和出色的性能为目标，正在快速获得开发者社区的青睐。

本指南将以 ethers.js 为例进行详细讲解，因为它在易用性和功能之间取得了很好的平衡。

---

第二步：为你的项目选择环境

你可以在两种主要环境中使用 Web3 包：

• 浏览器环境 (Browser Environment)：用于构建前端 DApp，用户通过浏览器直接与你的应用交互，因此所有代码都将在用户的设备上运行。
• Node.js 环境 (Node.js Environment)：用于构建后端服务、脚本或自动化工具，代码将在服务器上运行，安全性更高，可以处理敏感信息（如私钥）。

在浏览器环境中导入 (前端 DApp)

假设你正在使用 Vite 或 Create React App 等 modern 前端框架构建一个 React 应用。

初始化项目并安装依赖

如果你的项目还没有初始化,请先创建一个：

# 进入项目目录
cd my-dapp

通过 npm 或 yarn 安装 ethers.js：

# 使用 npm
npm install ethers
# 或者使用 yarn
yarn add ethers

在代码中导入并使用

安装完成后,你就可以在任何组件或工具文件中导入 ethers 并开始使用了。

下面是一个简单的例子,在 React 组件中连接到用户的钱包（如 MetaMask）并打印其地址。

// src/App.jsx
import { useState, useEffect } from 'react';
import { ethers } from 'ethers';
function App() {
  const [account, setAccount] = useState(null);
  useEffect(() => {
    // 检查浏览器是否安装了以太坊提供商（如 MetaMask）
    if (window.ethereum) {
      window.ethereum.request({ method: 'eth_requestAccounts' })
        .then(accounts => {
          if (accounts.length > 0) {
            setAccount(accounts[0]);
          }
        })
        .catch(err => {
          console.error("用户拒绝了连接请求", err);
        });
    } else {
      alert("请安装 MetaMask 或其他兼容的 Web3 钱包！");
    }
  }, []);
  return (
    <div className="App">
      <h1>我的第一个 DApp</h1>
      {account ? (
        <p>已连接的账户: <strong>{account}</strong></p>
      ) : (
        <p>正在连接钱包...</p>
      )}
    </div>
  );
}
export default App;

代码解析：

1. import { ethers } from 'ethers';：从已安装的 ethers 包中导入主库。
2. window.ethereum：这是 MetaMask 等钱包注入到浏览器全局环境中的对象，是前端 Web3 应用的入口点。
3. window.ethereum.request(...)：通过这个对象，我们可以请求用户授权连接钱包。

当你运行 npm run dev 启动项目后，打开浏览器开发者工具的 Console，就能看到连接成功的日志。

在 Node.js 环境中导入 (后端/脚本)

假设你需要编写一个 Node.js 脚本来查询某个区块链地址的余额。

初始化项目并安装依赖

创建一个新的项目目录并初始化 npm：

mkdir my-node-script
cd my-node-script
npm init -y

安装 ethers.js：

npm install ethers

在代码中导入并使用

创建一个 index.js 文件，编写你的脚本。

// index.js
const { ethers } = require("ethers");
// 1. 创建一个 Provider
// Provider 是一个只读对象，用于连接到以太坊网络，读取区块链数据。
// 你可以使用 Infura 或 Alchemy 这样的服务提供商。
const provider = new ethers.providers.JsonRpcProvider("https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID");
// 2. 定义要查询的地址
const address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"; // 以太坊创始人 Vitalik Buterin 的地址
// 3. 获取地址的 ETH 余额
async function getBalance() {
  try {
    const balance = await provider.getBalance(address);
    // ethers.utils.formatEther 将大单位的 wei 转换为易读的 ETH
    console.log(`地址 ${address} 的余额是: ${ethers.utils.formatEther(balance)} ETH`);
  } catch (error) {
    console.error("查询余额失败:", error);
  }
}
getBalance();

如何运行：

1. 将上面的代码保存为 index.js。

2. 重要：将 YOUR_INFURA_PROJECT_ID 替换为你自己在 Infura 或 Alchemy 上创建的项目 ID。

3. 在终端中运行脚本：

   node index.js

代码解析：

1. const { ethers } = require("ethers");：在 Node.js 环境中，我们使用 require 来导入模块。
2. ethers.providers.JsonRpcProvider：这是连接到以太坊节点的核心，我们使用一个公共的 RPC 端点（由 Infura/Alchemy 提供）来获取数据，而不需要自己运行一个全节点。
3. provider.getBalance(address)：这是一个异步操作，用于查询指定地址的余额。

总结与关键点

核心要点回顾：

1. 选择合适的库：根据项目需求选择 ethers.js, web3.js 或 viem。
2. 区分环境：前端依赖钱包注入，后端依赖 RPC 节点连接。
3. 安装依赖：使用 npm install 或 yarn add 将包添加到你的项目中。
4. 正确导入：前端用 import，后端用 require。
5. 安全第一：切勿在前端代码中硬编码私钥或助记词，私钥应安全存储在后端服务器或环境变量中。

通过以上步骤,你已经掌握了 Web3 包导入工程的基本方法，这只是 Web3 开发的冰山一角，接下来你可以探索智能合约交互、交易签名、事件监听等更高级的主题，祝你编码愉快！