简介面向区块链方向毕业设计与课程设计需求这份基于Truffle与Solidity的以太坊宠物商店Dapp源码包提供完整可运行的前端交互、智能合约与部署配置。压缩包共2001个文件包含1148个JS脚本、434个Markdown文档、298个JSON配置、61个HTML页面及CSS样式等整体约14.08MB目录组织清晰便于按模块通读和二次开发。已有149人学习源码经导师指导并通过答辩评审95分所有代码均测试运行正常。资源除完整源码外还附详细设计文档、部署说明与全部资料覆盖宠物领养场景下的合约状态管理、事件触发和界面联动等核心环节适合计算机相关专业学生用于毕设课设、项目演示或区块链进阶练习。使用者可在现有基础上修改功能也可直接作为立项演示快速理解Dapp开发全流程。1. 为什么宠物商店Dapp是入门以太坊开发最值得复现的一条链路「基于truffleSolidity以太坊智能合约的宠物商店Dapp」看起来像课程作业但它实际上把以太坊开发的最小闭环压缩进了一个项目用 Solidity 写合约、用 Truffle 做编译和部署、用 Web3 把合约接进网页、再用浏览器钱包触发一笔真实上链的领养交易。这就是 Truffle 官方教程里经典的 Pet Shop 路线也是我建议新手第一个完整复现的项目。适合两类人已经会 JavaScript、知道区块链大概是什么但没动手写过合约的开发者以及想把「合约 前端 钱包」整条链路跑通、再换到自己业务场景里的从业者。做完它你就有了一套能反复套用的脚手架。2. 把 Truffle 脚手架跑起来目录结构、环境版本与首个编译产物2.1 为什么要选 Truffle而不是裸写 solc 编译脚本刚接触 Solidity 时最容易踩的坑是「合约写好了但不知道下一步干什么」。裸写 solc 只能拿到 ABI 和 Bytecode后面还有迁移脚本、网络配置、测试框架、前端集成全都要自己拼。Truffle 的价值在于把这条链串起来了它内置编译器、迁移器、测试框架和网络管理一个truffle migrate就能把合约部署到指定链上并把部署地址写进 JSON 文件供前端读取。这几年 Hardhat、Foundry 也很流行但如果你手里这套宠物商店项目的资料是基于 Truffle 写的我建议先把 Truffle 跑通再横向对比别的框架。因为 Truffle 的约定式目录结构contracts、migrations、test对理解「编译产物从哪来、前端怎么找到合约地址」更直观排错时也更容易定位。2.2 初始化项目与目录结构三种命令的区别常见做法是直接用 Truffle 的官方模板而不是从零建目录。先全局安装再初始化# 安装 Truffle建议 Node.js 16 npm install -g truffle # 创建一个空白项目目录并进入 mkdir pet-shop cd pet-shop # 方式一拉取官方宠物商店模板本项目就是这个结构 truffle unbox pet-shop # 方式二只生成空白 Truffle 骨架自己写合约 # truffle initunbox和init的区别要讲清楚init只给你四件套——contracts、migrations、test、truffle-config.jsunbox pet-shop还会额外带一套前端页面src 目录和宠物图片数据你打开页面就能在浏览器里点按钮。这个项目标题里写的是宠物商店 Dapp对应结构就是后者。模板拉下来后目录是pet-shop/ ├── contracts/ # Solidity 合约文件 │ ├── Adoption.sol │ └── Migrations.sol ├── migrations/ # 部署脚本按编号顺序执行 │ ├── 1_initial_migration.js │ └── 2_deploy_contracts.js ├── test/ # Truffle 测试文件 ├── src/ # 前端页面HTML JS ├── truffle-config.js # 网络、编译器版本配置 └── package.json这里最容易翻车的是 Node 版本。Truffle 5.x 对 Node 12 以下的支持很差安装时会直接报语法错误建议先node -v确认版本再决定装不装。另一个常见误用是直接用truffle init生成空白骨架然后自己复制合约和前端结果 truffle-config.js 里的网络配置、合约地址路径和前端代码对不上排查半天。我一般会先unbox跑通再逐步删掉不需要的文件。2.3 编译产物是前端和合约之间的“黑匣子钥匙”执行编译# 编译 contracts 目录下所有 .sol 文件 truffle compile编译完成后build/contracts/下会生成Adoption.json和Migrations.json。这个 JSON 里最关键的两个字段是abi和networks。abi是合约的接口描述——前端靠它知道合约有哪些方法、参数类型、返回值类型networks记录的是「这个合约部署在哪个链、什么地址」前端拿到它才能找到合约。如果前端一直连不上合约第一件事就是打开这个 JSON看networks下有没有你当前链的 network id这是排查顺序里最早的节点。另一个值得注意的点是truffle-compile只负责编译不会重新部署改了合约后部署也要带着--reset一起做否则链上还是旧代码。3. 宠物领养合约与迁移脚本把「谁领养了哪只宠物」写进链上3.1 Adoption.sol 的结构与状态变量设计思路宠物商店的核心业务是「标记某只宠物被某个地址领养」。先看合约本体这个项目里的经典版本是这样// SPDX-License-Identifier: MIT pragma solidity ^0.6.0; contract Adoption { // 宠物 ID 从 0 到 15adopters[petId] 就是宠物当前的主人 address[16] public adopters; // 领养把调用者地址写进对应位置 function adopt(uint petId) public returns (uint) { require(petId 0 petId 15, invalid pet id); adopters[petId] msg.sender; return petId; } // 查询返回所有宠物当前的主人方便前端一次性渲染 function getAdopters() public view returns (address[16] memory) { return adopters; } }几个设计决策值得细说。第一这里用的是固定长度数组address[16]而不是 mapping因为前端页面需要一次性拿到 16 只宠物的领养状态数组可以整体返回mapping 做不到。第二adopters用了public修饰Solidity 会自动生成一个adopters(uint)的 getter但每次只能查一只前端要渲染整页还是得靠getAdopters()。第三msg.sender是 Solidity 内置的全局变量代表调用这笔交易的地址——宠物商店不需要注册、登录领养人以钱包地址为准这就是 Dapp 和传统网站最本质的区别。第四require(petId 0 petId 15)看起来是常识性校验但它同时也是 gas 防线没有它非法 petId 也不会报错而是静默写进数组前端显示就会出现「第 18 只宠物被领养」这种诡异状态。如果拿到的源码是pragma solidity ^0.5.0的写法多数情况下只需注意构造函数写法差异其他逻辑通用。我这里按 0.6.x 演示因为这个项目最常见的模板就是 0.5/0.6 时代写的truffle-config.js里配的 solc 版本要以你本地装的实际版本为准。3.2 迁移脚本怎么决定合约部署顺序Truffle 部署不靠命令行参数指定合约而是通过migrations/目录下的 JavaScript 脚本。宠物商店只有两个合约需要部署Migrations.sol是 Truffle 自己用来记录部署状态的先部署业务合约后部署// migrations/1_initial_migration.js // 部署 Migrations.solTruffle 用它跟踪当前部署到哪一步 const Migrations artifacts.require(Migrations); module.exports function (deployer) { deployer.deploy(Migrations); };// migrations/2_deploy_contracts.js // 部署真正的业务合约 Adoption const Adoption artifacts.require(Adoption); module.exports function (deployer) { deployer.deploy(Adoption); };artifacts.require是 Truffle 提供的全局方法作用是从编译产物里加载合约的 ABI 和 Bytecode部署时会自动带着它们发起交易。deployer.deploy是异步任务顺序敏感如果业务合约的构造函数需要 Migrations 的地址就必须等 1 号脚本执行完。这里的参数只有合约本身因为 Adoption 构造函数没有入参真实项目里合约构造函数如果有参数可以这样传deployer.deploy(Adoption, arg1, arg2, { from: deployer.accounts[0], gas: 3000000 });花括号里的from和gas是交易参数from默认取 Truffle 配置里第一个可用账户gas不写就走链上默认值。很多初学者在这里犯一个错误改完合约只truffle migrate不--resetTruffle 部署脚本是幂等记录的改过的合约第二次部署会被跳过前端看到的还是旧地址。我一般会这样truffle migrate --reset --network development3.3 在 Ganache 本地链上完成部署并核对交易回执Truffle 默认连的本地链是 Ganache。先启动它再执行部署# 启动 Ganache CLI如果图形版则直接创建 workspace ganache-cli -p 8545 -m candy maple cake sugar pudding cream honey rich smooth crumble sweet treat # 新开终端进入项目目录后执行 truffle migrate --network development-p指定端口-m指定助记词。为什么要固定助记词因为 Ganache 每次启动都随机生成 10 个地址前端和测试脚本里如果有写死的账户地址链一重启就全废固定助记词等于让地址保持不变。部署成功的输出会包含2_deploy_contracts.js Deploying Adoption -------------------- transaction hash: 0x1234... contract address: 0x8CdaF0... block number: 3 gas used: 120000contract address是后续前端要连的地址gas used是这次部署实际消耗的 gas不是交易费上限。这两个值建议随手记下来后端联调时有用。这里有一个高频翻车点Ganache 图形版默认端口是 7545CLI 版默认是 8545而 Truffle 模板里的truffle-config.js配的往往是 8545。如果你开了图形版没改端口truffle migrate会一直报Error: Connection error。解决方法是看配置文件把端口对齐// truffle-config.js 里的 development 网络 development: { host: 127.0.0.1, port: 8545, // 改成 7545 就匹配图形版 Ganache network_id: * // 匹配任意网络 ID本地调试用 }network_id: *的含义是不校验网络 ID这在本地调试没问题但部署到正式测试网时建议写成确切的链 ID避免误发到别的链上。4. 让宠物商店前端真正调用合约从 Web3.js 到页面渲染4.1 两条连合约的路线直接 Web3 还是 truffle-contract前端和合约交互有两条路线。宠物商店这类老项目模板里常见的是用truffle-contract封装好的对象它会把build/contracts/Adoption.json里的 ABI 和网络地址自动接好代码更短而更通用、更接近真实生产环境的做法是直接用 Web3.js 的new web3.eth.Contract(abi, address)。我建议按后一种方式理解因为 truffle-contract 很多项目已不再维护而你将来接 Uniswap、接 NFT 合约用的都是 Web3.js 或 ethers.js 的裸写法。两套思路的对比方式合约地址获取方法调用适用阶段truffle-contract从 JSON 的 networks 自动读contractInstance.adopt(...)模板演示、教学Web3.js 原生 Contract手动指定 ABI addresscontract.methods.adopt(...).send(...)生产、接第三方合约真相是不管哪种写法浏览器里都得有 MetaMask或同类钱包注入的 provider真正签名和广播交易的是钱包前端只是替你把交易参数组装好。理解这一点前端代码就不会写成「我直接拿私钥在页面里 sign」这种危险方案。4.2 页面交互四步注入、实例化、发送、查询核心逻辑在src/js/app.js缩写如下// 第一步拿到钱包注入的 provider if (window.ethereum) { web3 new Web3(window.ethereum); try { // 新版 MetaMask 的授权方式 await window.ethereum.request({ method: eth_requestAccounts }); } catch (e) { console.error(用户拒绝了授权, e); } } else if (window.web3) { // 旧版 MetaMask 兼容 web3 new Web3(window.web3.currentProvider); } else { alert(请先安装 MetaMask); } // 第二步用编译产物里的 ABI 和部署地址创建合约实例 const contract new web3.eth.Contract(petAbi, contractAddress); // petAbi 来自 build/contracts/Adoption.jsoncontractAddress 来自其 networks 字段 // 第三步领养——这是一笔交易会弹 MetaMask、消耗 gas const accounts await web3.eth.getAccounts(); await contract.methods.adopt(petId).send({ from: accounts[0], gas: 500000 });这段代码里三个参数最容易出错。第一eth_requestAccounts是当前推荐的授权方法旧代码里的window.ethereum.enable()已废弃新钱包会直接拒绝如果你是拿老模板改的这行必须换。第二gas: 500000是交易 gas 上限不是「你要付 50 万 gas」实际消耗按调用逻辑算设太低会报out of gas设太高也不会多花钱——链上按实际用掉的算多给的会退回。第三send之前一定要有from地址否则 MetaMask 会弹「unknown account」。查询类调用比如读取领养列表不需要钱包直接.call()就行// 查询读取链上数据不产生交易 const adopters await contract.methods.getAdopters().call();call和send的区别是新手最容易混的send改变链上状态要签名、要 gas、要走共识call只是读免费且不经过钱包确认。领养操作必须用send刷新页面显示用call代码里写反就会看到按钮点了没反应或者 MetaMask 弹出一个 gas 为 0 的怪交易。4.3 交易确认后页面为什么还要重新查询一次这是 Dapp 前端和传统前端最大的体验差异。传统网站表单提交后后端改数据库前端重新拉接口就完事了Dapp 里send返回的只是一个 pending 状态的交易哈希链上状态什么时候更新、是否成功要等区块确认。宠物商店的常见误用是页面加载时查一次getAdopters()领养成功后什么都不做——于是列表停留在旧状态。正确做法是在send的receipt回调里再查一次await contract.methods.adopt(petId).send({ from: accounts[0], gas: 500000 }) .on(receipt, async (receipt) { // 交易上链成功重新拉取领养列表并渲染 const adopters await contract.methods.getAdopters().call(); renderAdopters(adopters); }) .on(error, (err) { console.error(领养失败, err); });这一点你只跑一次可能无感但把 Dapp 交给别人体验时对方会照着「点击领养 → 列表立刻变化」的惯性预期来操作如果页面不变就会以为是 bug。这里也可以顺手做一笔乐观更新点击按钮先在前端把宠物图片打上「已领养」标记等 receipt 回来再修正体验会好很多。5. 宠物商店 Dapp 常见问题排查五个把新手卡住的地方5.1 编译报错「ParserError: Expected identifier」现象truffle compile直接失败报错指向pragma solidity那一行。原因本机 Truffle 内置的 solc 版本和合约里pragma声明不兼容比如合约要求^0.6.0编译用的是 0.8.x。解决在truffle-config.js里固定编译器版本compilers: { solc: { version: 0.6.6, // 与合约 pragma 匹配 } }配置后删掉build/目录重新编译。这件事看起来是环境问题实际上是 Solidity 的老传统0.5、0.6、0.8 三代语法差异不小很多老教程的合约代码不能直接在新编译器上跑。如果报错出现在构造函数、require字符串优先怀疑版本。5.2 前端一直连不上合约地址显示 0x0 或旧地址现象MetaMask 正常、页面能打开但调合约一直报invalid address或者读出来的数据是空的。原因前端从Adoption.json里读到的networks没有当前 Ganache 的 network id或者部署后没重新编译前端还在用上一次的合约地址。这个坑最阴的地方是「页面没报错但数据永远是初始状态」。解决部署后检查build/contracts/Adoption.json里的networks字段# 用 node 直接看 networks 字段 node -e const crequire(./build/contracts/Adoption.json); console.log(c.networks)如果输出的 network id 不是当前 Ganache 的 idGanache 默认 5777说明部署和编译不一致。执行truffle migrate --reset后再看。另外一个隐藏点如果你手动把合约地址写死在app.js里换网络、重跑 Ganache 后必然翻车。我一般从 JSON 里动态读地址不让地址出现在业务代码里。5.3 MetaMask 一直不弹窗或弹了之后授权失败现象点了「领养」按钮浏览器下方没有任何反应控制台报MetaMask - RPC Error: unauthorized。原因前端还在用window.ethereum.enable()这种旧 API新钱包已移除或者 MetaMask 当前选的是 Ethereum 主网而你的合约在本地 Ganache 上网络不匹配。解决代码改成eth_requestAccounts同时确认 MetaMask 里手工添加了本地网络——RPC URL 写http://127.0.0.1:8545或 7545Chain ID 写 5777或 1337。注意 Ganache 图形版的端口配置、Chain ID 都和 Truffle 默认值可能不同要以你 Ganache workspace 里显示的为准。这里有个血泪经验不要用「localhost」代替「127.0.0.1」有些机器 localhost 解析到 IPv6钱包会连接失败。5.4 领养成功后列表不刷新刷新页面才恢复现象MetaMask 确认交易、receipt 也拿到了但页面上的宠物图片还是「可领养」状态。原因前端只在页面加载时查询了一次没有在交易确认后重新call。这个不算合约问题是交互设计漏了。解决在.on(receipt)回调里重新调getAdopters()并重新渲染见 4.3。有经验的人还会顺手处理失败分支拿不到 receipt 时把按钮恢复成可点状态提示用户重试——不做这步用户会下意识狂点按钮排出好几笔重复交易。5.5 重启电脑或 Ganache 后合约地址全部失效现象第二天打开电脑启动 Ganache前端访问合约变成「不存在」或返回空。原因Ganache 是内存链重启后链上数据清空所有合约地址都无意义。解决开发机建议用「固定助记词 持久化数据」的方式启动ganache-cli -m 你固定的助记词 --db /path/to/chain-data--db指定链数据落盘目录配合固定助记词重启后地址不变、账户不变、合约还能用。这算是本地开发的后悔药不配置的话每次重启都要重新migrate --reset而且前端地址要跟着改。另外提醒Ganache 的私密密钥仅用于本地开发不要拿有资产的钱包助记词去喂 Ganache那些地址被任何人看到都能直接取走测试币。6. 进阶验证把「能跑」变成「能复用」的一条测试习惯项目跑通之后我建议立刻做一件事给 Adoption 合约补一个最小测试用truffle test把它变成可回归的东西。测试文件放test/adoption.jsconst Adoption artifacts.require(Adoption); contract(Adoption, (accounts) { const [owner, adopter] accounts; it(应该记录领养人地址, async () { const instance await Adoption.deployed(); await instance.adopt(8, { from: adopter }); const adopters await instance.getAdopters(); assert.equal(adopters[8], adopter, 第 8 只宠物的主人应该是 adopter); }); it(同一只宠物第二次领养应如何处理, async () { const instance await Adoption.deployed(); await instance.adopt(3, { from: adopter }); // 这里因为当前合约没做防重复校验是可以再次写入的 // 如果你要把它当生产合约应该在这里加 require(adopters[petId] address(0)) const adopters await instance.getAdopters(); assert.notEqual(adopters[3], accounts[2], 不该被第三个地址覆盖); }); });第二个测试想说明的是宠物商店作为教学项目它的adopt没有做「已被领养则拒绝」的校验。真实业务里这是必须补的逻辑否则后领养的人能直接覆盖前人记录。常见做法是在adopt开头加一句require(adopters[petId] address(0), pet already adopted)。测试的意义不在于证明模板能用而在于当你把宠物商店改成「房屋租赁」「二手交易」时有一层安全网兜住合约状态变更。我自己的习惯是跑通一个 Dapp 方向后把三样东西记进项目 README使用的链 ID、最后一次部署的合约地址、对应的build/contracts哈希。看起来是小事但两周后回来改需求最常卡住的问题不是写不出代码而是想不起来「上次那个合约到底部署在哪个网络」。这套从编译到测试、从本地链到前端联调的习惯比项目本身更值得带走。希望帮到你。本文还有配套的精品资源点击获取