1. 项目概览与核心价值最近在整理自己的代码库发现这些年陆陆续续攒下了不少Web3相关的示例项目从最基础的ERC20代币合约到结合了预言机的DeFi前端再到一些新兴公链的探索。这些代码散落在各处每次想找个参考或者教新人入门都得翻半天。索性我把它们都归拢到了一个仓库里并做了系统性的整理和优化这就是luzhenqian/web3-examples这个开源仓库的由来。这个仓库不是一个单一的项目而是一个面向开发者的Web3实战代码示例集合。它的核心价值在于为不同阶段的开发者——无论是刚听说“智能合约”这个词的新手还是想快速验证某个链上交互逻辑的老手——提供一个开箱即用、可直接复现的参考。你不用再从零开始搭建环境、配置网络、调试那些令人头疼的依赖这里已经为你准备好了经过验证的、可直接运行的代码片段和完整项目。仓库覆盖了以太坊、Solana、比特币、TON等多个主流区块链生态内容横跨智能合约Solidity/Rust、前端Next.js/React、后端脚本以及核心概念教学。无论你是想学习如何发行一个自己的NFT还是想了解如何在前端集成钱包并读取链上数据或是想研究跨链交互都能在这里找到对应的“脚手架”。接下来我将带你深入这个宝库拆解它的结构、运行方式并分享我在构建这些示例时积累的一手经验和避坑指南。2. 仓库结构与技术栈深度解析2.1 多链并行的目录架构设计打开仓库你会发现它的结构非常清晰完全是按区块链类型来组织的。这种设计思路源于一个很实际的考量不同区块链的开发栈、工具链和思维方式差异巨大。把它们混在一起只会增加学习和检索的复杂度。web3-examples/ ├── ethereum/ # 以太坊生态核心 │ ├── contract/ # Solidity智能合约ERC20, ERC721, 可升级合约等 │ ├── frontend/ # Next.js Wagmi RainbowKit 前端DApp │ └── mock/ # 本地测试用的模拟数据 ├── solana/ # Solana生态 │ └── solana-pyth-price-feeds/ # 使用Pyth预言机的价格展示DApp ├── bitcoin/ # 比特币生态 │ └── bitcoinjs-lib/ # 使用bitcoinjs-lib进行基础交易构造的示例 ├── ton/ # TON生态 │ └── wallet/ # TON钱包集成与基础交互示例 ├── blockchain/ # 通用区块链概念哈希、默克尔树、简单PoW模拟 ├── script/ # 实用脚本如批量查询、数据抓取 └── docs/ # 补充说明文档为什么选择这样的技术栈组合以太坊部分Next.js Wagmi RainbowKit这是目前构建以太坊DApp前端的事实标准组合。Next.js提供优秀的开发体验和SEO能力Wagmi是一套完整的React Hooks for Web3极大地简化了连接钱包、读取合约、发送交易等逻辑RainbowKit则提供了美观、易用且可定制的钱包连接按钮组件。这个组合能让你用最少的代码构建出生产级的DApp界面。Solana部分solana/web3.js AnchorSolana生态中solana/web3.js是官方RPC客户端库而Anchor框架则相当于以太坊的HardhatTruffle它通过一套IDL接口描述语言和Rust宏让智能合约的开发和前端调用变得类型安全和高度自动化。示例中选择Pyth预言机是因为它是Solana上最重要、最常用的去中心化预言机网络集成它具有很高的实战价值。比特币部分bitcoinjs-lib对于比特币复杂的智能合约并非其强项因此示例聚焦于更底层的交易构造和签名这是理解比特币脚本和UTXO模型的基础。bitcoinjs-lib是社区最成熟、应用最广的JavaScript比特币库。TON部分TON ConnectTON生态有其独特的钱包协议TON Connect和消息模型。示例展示了如何集成TON Connect来连接流行的Tonkeeper等钱包并执行基础的转账和合约调用。注意每个子目录下都有独立的README.md文件详细说明了该项目的具体技术栈、环境要求和运行步骤。在动手之前务必先阅读对应的README。2.2 环境准备绕过网络与配置的“暗礁”Web3开发的第一道坎往往不是代码而是环境。很多服务和工具如某些测试网水龙头、文档站点、甚至npm包源的访问可能不稳定或受限这会让新手在第一步就卡住。1. 网络访问策略仓库中部分示例的前端或脚本可能需要访问外部API如Alchemy、Infura、公共RPC节点。如果你的本地网络环境无法直接访问需要自行配置可靠的网络代理。这里的关键是找到一个稳定、低延迟的代理服务并将其配置到你的系统或终端环境中。对于前端项目通常不需要在代码层面特殊处理只需确保你的开发机网络通畅即可。对于命令行操作如使用curl或某些CLI工具你可能需要在终端中临时设置代理环境变量。2. 关键服务API密钥申请几乎所有示例都依赖于第三方服务你必须提前申请好免费的API KeyAlchemy用于以太坊节点的JSON-RPC访问。去Alchemy官网注册创建一个App选择Sepolia测试网即可获得HTTPS和WSS的Endpoint。这是前端项目连接区块链所必需的。Infura功能与Alchemy类似同样是智能合约部署和交互时常用的节点服务。注册后创建一个Project获取Project ID。其他服务根据具体示例可能还需要Pyth预言机的价格ID、TON的RPC节点等这些在各自的README中都有指引。3. 核心开发环境配置Node.js npm/yarn/pnpm确保安装LTS版本的Node.js建议v18。仓库内项目通常使用npm但你也可以使用yarn或pnpm。代码编辑器强烈推荐VSCode并安装Solidity、Rust等相关插件以获得语法高亮、代码提示和格式化支持。钱包准备一个测试用的钱包如MetaMask用于EVM链和Phantom用于Solana。务必创建或导入一个测试网专用账户并保管好助记词切勿使用存有主网资产的账户。3. 核心示例项目实操指南3.1 以太坊全栈DApp实战从合约到前端让我们以ethereum/目录下的项目为例走通一个完整的DApp开发流程。这里包含一个简单的“Noah Token”ERC20和一个“Noah NFT”ERC721合约以及与之配套的Next.js前端。第一步智能合约部署与测试进入合约目录cd ethereum/contract。环境配置复制.env.example为.env填入你的Infura Project ID和测试网钱包的私钥务必使用测试网账户。INFURA_API_KEYyour_infura_project_id_here TESTNET_PRIVATE_KEYyour_test_wallet_private_key_here安装依赖与编译运行npm install安装Hardhat等依赖。然后执行npx hardhat compile来编译Solidity合约。如果遇到Solidity版本问题检查hardhat.config.js中的编译器配置。部署到测试网运行部署脚本例如npx hardhat run scripts/deploy_noah_token.js --network sepolia。脚本执行成功后控制台会打印出合约的部署地址请务必保存这个地址。验证合约可选但推荐为了能在Etherscan等区块浏览器上公开查看合约源码可以使用Hardhat的验证插件。这需要在.env中配置ETHERSCAN_API_KEY并运行npx hardhat verify --network sepolia DEPLOYED_CONTRACT_ADDRESS。实操心得部署合约时Gas费是一个现实问题。Sepolia测试网的ETH可以通过官方水龙头获取但有时会枯竭。多准备几个水龙头来源如Alchemy、Infura自家提供的轮流尝试。部署后建议立即在区块浏览器上查看交易状态确认合约创建成功。第二步前端DApp集成与运行进入前端目录cd ethereum/frontend。环境配置同样复制.env.example为.env。这里需要填入刚才部署的合约地址以及你的Alchemy API Key用于前端连接区块链。NEXT_PUBLIC_NOAH_TOKEN_ADDRESS0xYourDeployedTokenAddress NEXT_PUBLIC_ALCHEMY_API_KEYyour_alchemy_api_key_here NEXT_PUBLIC_WALLET_CONNECT_PROJECT_IDyour_walletconnect_project_id # 用于RainbowKitWalletConnect Project ID需要去其官网注册获取这是RainbowKit支持钱包连接所必需的。安装与运行执行npm install然后npm run dev。如果一切顺利浏览器打开http://localhost:3000就能看到应用界面。连接钱包与交互点击“Connect Wallet”按钮选择MetaMask并切换到Sepolia测试网。连接成功后前端会自动读取你钱包的地址和余额。界面中应该会有“Mint Token”或“Mint NFT”的按钮点击即可与刚才部署的合约进行交互。首次交互需要钱包确认并支付Gas费。前端代码核心逻辑解析 前端的关键在于wagmi的配置通常在app/providers.tsx或类似文件中和合约交互Hook的使用。例如读取代币余额的代码大致如下import { useAccount, useReadContract } from wagmi; import { noahTokenAbi } from /abis; // 从编译好的ABI文件导入 function BalanceDisplay() { const { address } useAccount(); const { data: balance } useReadContract({ address: process.env.NEXT_PUBLIC_NOAH_TOKEN_ADDRESS, abi: noahTokenAbi, functionName: balanceOf, args: [address], }); return divYour Balance: {balance?.toString()}/div; }useReadContract这个Hook会自动处理链的切换、数据的刷新极大地简化了开发。3.2 Solana与Pyth预言机集成solana/solana-pyth-price-feeds示例展示了如何在Solana上获取真实世界的资产价格。Pyth Network是一个专门提供高频金融市场数据的预言机。环境准备确保已安装Rust和Solana CLI。Solana CLI需要配置到Devnet测试网solana config set --url devnet。运行前端进入目录npm install后npm run dev。前端界面会展示通过Pyth获取的几种加密货币如BTC, ETH的实时价格。核心代码剖析关键文件是app/utils/pyth.ts。它展示了如何定义所需价格数据的Product ID和Price ID这些是Pyth网络中的唯一标识符。使用pythnetwork/client连接到Pyth的Devnet喂价程序。调用getPriceFeed方法获取价格数据对象。从价格数据中解析出当前价格、置信区间等信息。价格本身是以一种定点数格式存储的需要根据指数expo进行转换price priceFeed.price * 10^priceFeed.expo。注意事项Solana Devnet的RPC节点有时很慢或不稳定如果价格加载不出来可以尝试刷新或检查浏览器控制台网络请求。Pyth的价格数据有“置信区间”字段这在金融应用中非常重要它代表了价格的不确定性范围。在显示价格时可以考虑一并展示这个信息。3.3 比特币交易构造基础bitcoin/bitcoinjs-lib示例相对底层它不涉及智能合约而是演示如何用代码构造一笔标准的比特币交易。这对于理解比特币的UTXO模型和脚本系统非常有帮助。示例可能包含以下步骤创建一个比特币测试网testnet3的网络对象。生成或导入一个测试网私钥对应一个P2PKH地址。模拟一个未花费的交易输出UTXO作为输入。构造一笔向另一个地址转账的交易。对交易进行签名。将签名的交易序列化为十六进制格式理论上可以广播到网络。重要提示这个示例通常在本地模拟环境运行用于学习原理。切勿将私钥硬编码在将要公开或上线的代码中。在实际应用中签名环节应在安全的环境如后端服务器或硬件钱包中进行。4. 开发资源、工具与进阶路径仓库的README中列举了海量的学习资源、工具和平台这里我结合自己的经验做一些提炼和补充。4.1 学习路径建议对于初学者我建议遵循以下路径避免信息过载区块链概念入门先通过“区块链基础”类资源如CryptoZombies游戏、微软入门课程建立对区块、哈希、共识等基本概念的感性认识。专注一条链强烈建议从以太坊和Solidity开始。生态最成熟、资料最多、工作机会也最广。吃透仓库里的以太坊示例理解ERC20、ERC721标准掌握Hardhat和Wagmi的基本使用。智能合约安全在学会写合约之后立刻开始学习安全知识。OpenZeppelin的合约库不仅是工具也是最佳实践范本。Ethernaut攻防游戏是绝佳的练习场。拓展到其他链有了以太坊的基础再学习SolanaRust/Anchor或TONFunC会容易很多主要是熟悉其独特的工具链和账户模型。4.2 工具链与信息获取开发与调试Hardhat比Truffle更现代、更快的以太坊开发环境内置了强大的测试框架和本地网络是当前的主流选择。Remix IDE在线的Solidity IDE适合快速验证小段代码逻辑无需配置本地环境。Sepolia/Etherscan部署合约后立即在Etherscan上验证源码并利用其“Read Contract”和“Write Contract”功能进行手动交互测试非常直观。数据与调研Dune Analytics链上数据分析的神器。你可以编写SQL查询来提取、聚合和可视化区块链数据。学习看别人的看板Dashboard是理解一个项目真实活跃度的最好方式。DeFiLlama查看各条链上DeFi协议的总锁仓价值TVL排名是发现趋势和热门项目的好地方。RootData中文项目中很好的投融资信息查询站可以看一个项目背后有哪些投资机构。安全与风控GoPlus Security在交易任何陌生代币前将其合约地址丢进去进行安全检测可以有效识别“貔貅盘”只进不出的骗局合约、可疑权限等风险。OKLink Token Approval定期检查并撤销你对不常用DApp的无限代币授权这是一个非常重要的资产安全习惯。4.3 求职与社区Web3开发岗位分布在全球远程机会很多。除了仓库里列出的平台再多分享几个我常用的渠道Twitter/X关注你感兴趣的项目方、投资机构、知名开发者的账号。很多招聘信息会第一时间在这里发布。Discord加入你喜欢的项目的官方Discord很多团队会在#jobs或#contributors频道发布招募信息。积极参与社区讨论和建设是获得机会的绝佳方式。GitHub在相关领域的开源项目里提交有价值的PRPull Request是证明你技术能力最硬核的简历。5. 常见问题与排查实录在运行这些示例和日常开发中你肯定会遇到各种问题。下面是我总结的一些高频问题及解决方案。Q1: 运行npm install时依赖安装失败特别是与Web3或加密相关的包。可能原因网络问题导致某些包可能托管在特定网络上下载超时或本地Node.js/npm版本与项目不兼容。解决方案检查并确保你的网络连接稳定必要时配置npm镜像源如淘宝源或网络代理。确认Node.js版本。使用nvmNode Version Manager可以方便地切换版本。大部分项目要求Node.js v16或v18以上。尝试删除node_modules文件夹和package-lock.json文件然后重新运行npm install。对于特定于某个区块链的包如solana/web3.js可以查阅其官方文档看是否有特殊的安装要求。Q2: 前端成功启动但连接钱包后无法读取合约数据控制台报错如“Invalid JSON RPC response”。可能原因.env文件中的Alchemy API Key或合约地址配置错误。Alchemy项目没有正确配置到对应的网络例如前端要连Sepolia但Alchemy项目选的是主网。钱包没有切换到正确的网络例如合约部署在Sepolia但钱包还在以太坊主网。排查步骤仔细核对.env.local或.env文件中的每一个变量值确保没有多余的空格或换行。登录Alchemy仪表板确认你使用的API Key对应的项目网络是否正确。检查浏览器控制台Console的网络Network选项卡查看向Alchemy发出的RPC请求是否返回了错误信息。确保你的MetaMask等钱包已切换到示例要求的测试网络如Sepolia并且该测试网络已正确添加到钱包中。Q3: 部署智能合约时Hardhat脚本卡住或超时。可能原因RPC节点响应慢Gas价格设置不当测试网ETH不足。解决方案检查Gas和余额在部署前用npx hardhat run scripts/your_script.js --network sepolia --dry-run进行试运行可以预估Gas消耗。确保你的测试网账户有足够的ETH。更换RPC节点在hardhat.config.js中除了Infura也可以配置其他RPC提供商如Alchemy、Public Node的URL作为备选。调整超时设置在Hardhat配置中增加网络超时时间。sepolia: { url: https://eth-sepolia.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}, accounts: [process.env.TESTNET_PRIVATE_KEY], timeout: 60000, // 将超时设置为60秒 }Q4: 在Solana项目上交易发送失败错误信息晦涩难懂。可能原因Solana的错误信息通常以错误码形式返回需要翻译账户的SOL余额不足支付租金Rent或交易费程序执行逻辑错误。排查步骤检查余额使用solana balance 你的地址命令确认测试网SOL余额。可以通过solana airdrop 1在Devnet上获取免费SOL。解读错误码将错误码复制到搜索引擎或查阅Solana官方文档的错误码列表。常见的如InsufficientFundsForRent表示账户租金不足。使用Solana Explorer将失败交易的签名Signature复制到Solana Devnet的区块浏览器中查看详细的交易日志Logs里面通常会有更具体的错误描述。Q5: 如何获取测试网代币进行开发测试以太坊 Sepolia优先使用Alchemy、Infura官方提供的Sepolia水龙头它们通常更稳定。如果不行可以尝试社区维护的水龙头但要注意安全。Solana Devnet使用命令行solana airdrop 1 你的地址每次最多可申请2 SOL。通用建议为每个测试网准备一个专门的钱包并记录下助记词。不要在主网钱包里导入测试网私钥反之亦然以防误操作。