一个完整的 Web3 DeFi 教学项目，包含智能合约开发（Foundry）和前端应用（Next.js），用于教学演示和实战练习。
本项目包含以下核心模块：
- LaunchPad - 代币发行平台（买入/认领）
- Bridge - 跨链桥接（转账/状态追踪）
- DEX (Swap) - 去中心化交易所（代币交换）
- LP Staking (Pool) - 流动性质押（添加/移除流动性）
- Farm - 收益农场（质押/提现/收获奖励）
- Dashboard - 数据看板（资产概览/图表可视化）
``` Learn-Web3-FrontEnd/ ├── foundry-demo/ # Foundry 智能合约项目 │ ├── src/ # 合约源码 │ │ ├── RewardToken.sol │ │ ├── TokenA.sol │ │ ├── TokenB.sol │ │ ├── Swap.sol │ │ ├── Farm.sol │ │ └── LaunchPad.sol │ ├── script/ # 部署脚本 │ ├── test/ # 合约测试 │ └── out/ # 编译输出（ABI + Bytecode） │ ├── web3-dapp/ # Next.js 前端应用 │ ├── app/ # Next.js App Router 页面 │ │ ├── api/ # API 路由（Serverless） │ │ ├── dashboard/ # Dashboard 页面 │ │ ├── swap/ # DEX 交换页面 │ │ ├── pool/ # LP 质押页面 │ │ ├── farm/ # Farm 页面 │ │ ├── launchpad/ # LaunchPad 页面 │ │ └── bridge/ # Bridge 页面 │ ├── components/ # React 组件 │ ├── lib/ # 工具函数和配置 │ ├── public/abis/ # 合约 ABI 文件 │ └── .env.local # 环境变量（需手动创建） │ └── scripts/ # 工具脚本 └── verify.js # 项目自检脚本 ```
- Node.js 18+ 和 npm
- Foundry - 安装指南
- MetaMask 或其他 Web3 钱包
```bash git clone cd Learn-Web3-FrontEnd ```
```bash cd foundry-demo forge install forge build ```
验证编译输出： ```bash ls out/*/ # 应该看到 *.json 文件 ```
```bash cd ../web3-dapp npm run export-abis ```
这会将合约 ABI 从 `foundry-demo/out/` 复制到 `web3-dapp/public/abis/`
```bash
cp .env.local.example .env.local
```
```bash npm install ```
```bash npm run dev ```
```bash cd .. node scripts/verify.js ```
自检脚本会检查：
- ✅ Foundry 合约编译输出
- ✅ ABI 文件导出状态
- ✅ 环境变量配置
- ✅ 依赖安装情况
- ✅ 开发服务器状态
在 `web3-dapp/.env.local` 中配置以下变量：
```bash
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id
NEXT_PUBLIC_RPC_URL_SEPOLIA=https://sepolia.infura.io/v3/YOUR_KEY NEXT_PUBLIC_RPC_URL_MAINNET=https://mainnet.infura.io/v3/YOUR_KEY
NEXT_PUBLIC_REWARD_TOKEN_ADDRESS=0x... NEXT_PUBLIC_TKA_ADDRESS=0x... NEXT_PUBLIC_TKB_ADDRESS=0x... NEXT_PUBLIC_SWAP_ADDRESS=0x... NEXT_PUBLIC_FARM_ADDRESS=0x... NEXT_PUBLIC_LAUNCHPAD_ADDRESS=0x...
NEXT_PUBLIC_ETHERSCAN_API_KEY=your_api_key ```
-
获取测试 ETH
- 访问 Sepolia Faucet
- 获取测试 ETH
-
配置部署私钥 ```bash cd foundry-demo
echo "PRIVATE_KEY=your_private_key" > .env echo "SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY" >> .env ```
-
运行部署脚本 ```bash forge script script/Deploy.s.sol:DeployScript --rpc-url $SEPOLIA_RPC_URL --broadcast --verify ```
-
复制合约地址到 .env.local
- 部署成功后，将输出的合约地址填入 `web3-dapp/.env.local`
目标: 演示 AMM 自动做市商原理
```bash
cd web3-dapp && npm run dev
```
关键概念讲解:
- Constant Product AMM (x * y = k)
- Price Impact（价格影响）
- Slippage（滑点）
- ERC20 Approval 流程
目标: 演示流动性提供和收益
```bash
```
关键概念讲解:
- Liquidity Pool（流动性池）
- LP Token 机制
- Proportional Calculation（比例计算）
- Impermanent Loss（无常损失）
目标: 演示收益农场和质押奖励
```bash
```
关键概念讲解:
- Yield Farming（收益农场）
- APY 计算
- Reward Distribution（奖励分配）
- Compound Interest（复利）
目标: 演示代币发行和认购
```bash
```
关键概念讲解:
- Token Sale（代币销售）
- Vesting（归属期）
- Price Discovery（价格发现）
目标: 演示跨链转账概念
```bash
```
关键概念讲解:
- Cross-Chain Bridge（跨链桥）
- Lock & Mint 机制
- Relay 和验证
目标: 数据可视化和分析
```bash
```
关键概念讲解:
- TVL (Total Value Locked)
- Portfolio Tracking
- ECharts 可视化
```bash
cd foundry-demo && forge build
forge test
forge script script/Deploy.s.sol --rpc-url sepolia --broadcast
forge verify-contract <CONTRACT_ADDRESS> <CONTRACT_NAME> --chain sepolia ```
```bash cd web3-dapp
npm run dev
npm run build
npm start
npm run export-abis
npm run lint ```
```bash
node scripts/verify.js
curl http://localhost:3000/api/health curl http://localhost:3000/api/token/price ```
-
推送代码到 GitHub ```bash git add . git commit -m "feat: complete defi teaching project" git push origin main ```
-
导入到 Vercel
- 访问 https://vercel.com/new
- 选择你的仓库
- Root Directory: `./web3-dapp`（如果是 monorepo）
-
配置环境变量
- 在 Vercel Dashboard → Settings → Environment Variables
- 添加所有 `NEXT_PUBLIC_*` 变量
-
部署
- 点击 "Deploy"
- 等待构建完成（约 2-3 分钟）
```bash
npm i -g vercel
vercel login
cd web3-dapp vercel --prod ```
详细部署指南见：web3-dapp/DEPLOYMENT.md
```bash cd foundry-demo forge test -vv ```
```bash
cd web3-dapp npm run dev
curl http://localhost:3000/api/health curl http://localhost:3000/api/token/price curl http://localhost:3000/api/farm/stats ```
- 访问 http://localhost:3000
- 连接 MetaMask（Sepolia）
- 逐个测试各功能页面
- 验证交易执行和状态更新
详细测试指南见：web3-dapp/TESTING_GUIDE.md
原因: Next.js 缓存问题
解决方案: ```bash cd web3-dapp rm -rf .next npm run build ```
原因: 缺少 WalletConnect Project ID
解决方案:
- 访问 https://cloud.walletconnect.com
- 创建免费项目获取 Project ID
- 在 `.env.local` 中设置 `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`
原因: 合约地址未配置或网络错误
解决方案:
- 确认钱包连接到 Sepolia 测试网
- 检查 `.env.local` 中的合约地址是否正确
- 确保有足够的测试 ETH 支付 gas
原因: ABI 未导出或路径错误
解决方案: ```bash cd web3-dapp npm run export-abis ls public/abis/ # 验证文件存在 ```
原因: ECharts SSR 问题
解决方案:
- 已在 `LineChartEcharts.js` 中处理（动态导入）
- 如仍有问题，检查浏览器控制台错误
原因: 环境变量缺失或 RPC 节点问题
解决方案:
- 运行 `node scripts/verify.js` 检查配置
- 测试 RPC URL: `curl $NEXT_PUBLIC_RPC_URL_SEPOLIA`
- 查看 Vercel 日志（如果已部署）
更多问题见：web3-dapp/DEPLOYMENT.md
欢迎贡献代码、文档和教学案例！
- Fork 本仓库
- 创建特性分支 (`git checkout -b feature/AmazingFeature`)
- 提交更改 (`git commit -m 'Add some AmazingFeature'`)
- 推送到分支 (`git push origin feature/AmazingFeature`)
- 提交 Pull Request
- 智能合约使用 Solidity 0.8.20+
- 前端代码使用纯 JavaScript（禁用 TypeScript）
- 遵循 Next.js 15 App Router 规范
- 代币金额计算使用 `BigInt` 避免精度问题
- API 路由支持 Mock 模式（链不可用时）
- 所有页面支持三态处理（Loading/Empty/Error）
MIT License - 详见 LICENSE 文件
- 项目问题：提交 GitHub Issue
- 教学合作：[联系方式]
- 智能合约开发（Foundry + OpenZeppelin）
- 合约部署到 Sepolia 测试网
- 前端页面开发（Next.js 15 + App Router）
- 钱包集成（RainbowKit + Wagmi + Viem）
- 数据可视化（ECharts）
- API 路由（Serverless Functions）
- Vercel 部署配置
- 自检脚本和文档
- 单元测试覆盖率 > 80%
- E2E 测试（Playwright）
- 多链支持（Polygon, Arbitrum）
- 移动端优化
祝你学习愉快！Happy Learning! 🚀
如有问题，请运行 `node scripts/verify.js` 进行自检，或查看相关文档。