做DApp开发的人迟早会遇到这么一件事Solidity合约在Remix里测试了一百遍都正常但要真正把它发布到链上再写个前端去查询合约状态轮到自己敲代码时却不知道从哪下手。我第一次用Ethers.js发布合约和查询合约就是这么熬过来的网上教程一搜一大把但版本多是Ethers.js v5照着敲下来要么报错要么拿不到合约地址折腾到后半夜才明白是API版本变了。这篇文章把我沉淀下来的完整流程和踩坑记录整理出来从环境准备到部署上链从只读查询到事件监听最后是一段真实排错过程全程用的都是Ethers.js这套库。如果你已经了解智能合约的基本概念正想用JavaScript或TypeScript和合约交互这篇文章可以直接照着抄。如果你连Provider和Signer是什么都还模糊也不用担心第二章节会把整个运行模型讲清楚后面的代码就不会只是背API了。1. 我为什么用Ethers.js做合约发布和查询1.1 Ethers.js与web3.js的取舍链上交互的JavaScript库其实不只Ethers.js一个老牌的web3.js用户基数也很大。我最早写链上脚本用的就是web3.js后来新项目全面切到Ethers.js之后最大的感受是省心。web3.js的API设计偏底层很多操作要自己组装请求。想发一笔普通交易得自己拼eth_gasPrice、eth_call、eth_sendTransaction这些RPC调用出错时错误信息也经常要你自己去翻JSON-RPC文档。Ethers.js在这层做了大量封装provider、wallet、contract全给你管好调用合约写方法时就像调用普通async函数gas估算、nonce管理、交易签名、等待确认这些琐碎逻辑都替你处理了。然后是数据类型。链上很多数据是uint256在JavaScript里超过Number.MAX_SAFE_INTEGER就会丢精度。web3.js旧版本返回数值经常要靠BN或BigNumber去转不同库的BigNumber还不兼容特别容易踩坑。Ethers.js从v5开始用BigNumberv6直接改用原生BigInt和JavaScript天然对齐IDE里类型提示也清晰得多。做过链上数据索引的人应该懂这里省下来的精力不是一点半点。另外从工程角度看Ethers.js的模块化做得更好按需引入时能利用Tree-shaking把最终打出来的包体积压得很小。对前端项目来说这点很有吸引力。而且Ethers.js的官方文档有大量代码示例很多疑问不需要去翻源码就能找到答案。1.2 v5与v6的差异怎么快速识别关于版本有个比较现实的建议直接学Ethers.js v6。现在搜索Ethers.js教程还能搜出一堆v5的代码但v6已经发布很久了API更干净文档也更整齐。很多网上v5代码直接拿来用会报错先认清这个事实能少走很多弯路。需要迁移的话重点看这几个差异场景v5写法v6写法连接RPCnew ethers.providers.JsonRpcProvider(url)new JsonRpcProvider(url)部署后等待上链await contract.deployed()await contract.waitForDeployment()获取合约地址contract.addresscontract.target返回大数ethers.BigNumber原生BigInt地址校验ethers.utils.getAddress(addr)ethers.getAddress(addr)错误处理需要手动解包直接用code和reason定位原因我见过不少项目还跑在v5上如果要长期维护迁移成本其实没想象中高。但如果是新项目直接v6就好。下面所有代码统一用v6写法。2. 发布前必须搞懂的三层角色模型很多新手卡在Ethers.js部署合约这一步不是因为代码难写而是没弄明白几个核心对象各管什么。花十分钟把这个模型搞清楚比背二十个API都有用。2.1 Provider读数据靠它Provider是连接区块链节点的通道负责跟节点通信帮我读链上的数据。比如查地址余额、看交易状态、拿当前区块高度都走Provider。它不持有任何私钥也没有身份的概念可以理解成一条只读的HTTP通道只要拿到一个RPC URL就能创建。const { JsonRpcProvider } require(ethers); const provider new JsonRpcProvider(process.env.RPC_URL);刚接触Ethers.js的人容易把Provider和节点混为一谈。其实Provider只是一个客户端抽象真正干活的是背后那个RPC节点。Ethers.js支持的Provider类型也不少JsonRpcProvider是主力浏览器里还会用BrowserProvider去接管钱包插件暴露的接口。2.2 Wallet与Signer写数据靠它Wallet管的是写。它由私钥派生而来负责给交易签名证明这笔交易确实是这个人发出的。Wallet本身不直接连区块链它需要挂一个Provider才能把签名后的交易广播出去。创建Wallet有两种常见姿势// 方式一助记词 const wallet Wallet.fromPhrase(process.env.MNEMONIC, provider); // 方式二私钥 const wallet new Wallet(process.env.PRIVATE_KEY, provider);Wallet是Signer的最常用实现。今后你在API文档里看到Signer这个词不要慌它的核心能力就是持有密钥并签名Wallet就是它在本地私钥场景下的具体形态。凡是涉及转ETH、部署合约、调合约写方法的场景都必须有Signer参与。2.3 Contract连接ABI与链上状态的代理Contract是读写都管的代理。把ABI传进去之后Ethers.js会把合约里的函数变成JS方法。view或pure类型的函数直接读链上数据非view的函数自动生成一笔交易由指定的Signer签名后广播。这里有一个很多新手漏掉的细节Contract实例绑定的第三个参数决定它能不能发起写操作。绑定Provider的实例只能做只读操作绑定Signer的才能发起写操作。用代码说明更直观const { JsonRpcProvider, Contract } require(ethers); const provider new JsonRpcProvider(process.env.RPC_URL); // 第三个参数传provider这个实例只能读 const readOnlyContract new Contract(contractAddress, abi, provider); // 读没问题 await readOnlyContract.getCount(); // 调用写方法就会报错因为实例没有signer await readOnlyContract.increment();反过来创建实例时第三个参数传walletconst { Wallet, Contract } require(ethers); const wallet new Wallet(process.env.PRIVATE_KEY, provider); // 有签名能力的合约实例 const writableContract new Contract(contractAddress, abi, wallet); // 写方法能正常发起交易了 const tx await writableContract.increment();把这三个角色边界记清楚后面无论部署还是查询本质都是在这三个对象之间倒腾。3. 从零开始发布一份合约完整走通部署链路部署合约本质上是把一份带构造函数参数的字节码用一笔交易发送到链上。Ethers.js把这一层封装得很舒服但有几个细节值得拆开看。3.1 拿到可部署的ABI和Bytecode很多人忽略这一点Ethers.js只会帮你广播合约不会替你编译Solidity。所以在调用部署方法之前必须先把Solidity源码编译成ABI和Bytecode并且确保这两样东西来自同一份源码。最常见的做法是用Hardhat或Foundry编译。以Hardhat为例编译产物在artifacts/contracts/Counter.sol/Counter.json这个JSON里就有abi和bytecode两个字段。脚本里直接加载const contractJSON require(./artifacts/contracts/Counter.sol/Counter.json); const { abi, bytecode } contractJSON;如果只是临时实验也可以从Remix的编译面板里复制ABI和Bytecode。但Bytecode非常长手抄极易出错推荐用自动加载的方式。为了方便后面演示我准备一个极简Counter合约带一个构造函数参数还额外放了一个有返回值的写函数后面讲callStatic时要用// SPDX-License-Identifier: MIT pragma solidity ^0.8.19; contract Counter { uint256 public count; event Incremented(address indexed by, uint256 newCount); constructor(uint256 initialCount) { count initialCount; } function increment() public { count 1; emit Incremented(msg.sender, count); } function incrementAndGet() public returns (uint256) { count 1; emit Incremented(msg.sender, count); return count; } function getCount() public view returns (uint256) { return count; } }这个合约公开的count变量会自动生成一个同名的view函数所以getCount()和count()读到的值一样。我两个都留着方便后面演示查询函数的两种方式。3.2 用ContractFactory发起部署拿到ABI和Bytecode以后部署的入口是ContractFactory。这个类名很形象它就是生产合约实例的工厂你把ABI、Bytecode、Signer交给它它帮你造出合约并部署。const { ContractFactory, Wallet, JsonRpcProvider } require(ethers); const provider new JsonRpcProvider(process.env.RPC_URL); const wallet new Wallet(process.env.PRIVATE_KEY, provider); const factory new ContractFactory(abi, bytecode, wallet); // 构造函数参数是100对应Counter构造函数的initialCount const contract await factory.deploy(100);这里要特别提醒factory.deploy()返回的是一个合约实例但此刻交易可能还没上链。也就是说contract.target这个地址在区块确认之前实际上是不存在的。所以下一步必须等交易真正确认再对外使用这个地址。3.3 等待交易上链并拿到合约地址v6里等待部署完成的函数是waitForDeployment()v5叫deployed()。这个差别非常典型// v6写法 await contract.waitForDeployment(); const contractAddress contract.target; const deployTxHash contract.deploymentTransaction().hash; console.log(部署交易哈希:, deployTxHash); console.log(合约地址:, contractAddress);contract.target就是新合约地址v5里它叫contract.address。拿到地址后强烈建议用Provider再验证一遍合约是否真的在链上const code await provider.getCode(contractAddress); console.log(链上代码长度:, code.length);如果合约部署成功code会是一串十六进制字节码长度肯定大于2。如果返回的是0x说明该地址上没有合约要么部署没成功要么查询的网络不对。这一步验证在自动化脚本里非常实用能帮你第一时间发现问题。3.4 部署交易的Gas与环境细节部署交易和普通交易一样要花gas而且合约构造和初始化的成本不低。Ethers.js默认会调用eth_estimateGas估算gas但有两种情况我建议手动指定gasLimit一是构造函数逻辑比较复杂估算可能不准二是你想把gasLimit固定下来避免因节点估算波动导致交易失败。const contract await factory.deploy(100, { gasLimit: 3000000, });另一个容易忽略的问题是网络选择。Sepolia是目前最常用的以太坊测试网之一RPC地址可以从Alchemy、Infura或公共节点获取。部署到测试网需要一个带测试ETH的账户去对应测试网的faucet领一点就够用Sepolia的faucet有时候会网络抽风多试几个渠道就行。拿到测试币后脚本跑完记得把合约地址和交易哈希记录下来。后面的查询全部依赖这个地址。4. 查询合约有哪些玩法只读调用、staticCall与事件读取合约部署完真正的使用才开始。查询合约通常指一整类读取链上状态的操作包括直接调用view函数、模拟执行写操作、读历史事件、实时监听事件。每种场景对应的API在Ethers.js里差别很大。4.1 只读方法直接调用链上合约的view和pure函数不会改变状态所以Ethers.js生成的调用直接走eth_call不消耗gas也就是常说的免费查询。只要合约地址和ABI正确任何人都能读const { JsonRpcProvider, Contract } require(ethers); const provider new JsonRpcProvider(process.env.RPC_URL); const counter new Contract(contractAddress, abi, provider); const count await counter.getCount(); console.log(当前计数值:, count.toString());这里有个新手很容易忽略的点在Ethers.js v6里合约函数返回的uint256是JavaScript的bigint类型不是number。直接打印它时末尾会带个n比如100n。直接做运算没问题但如果要拼进字符串或传给JSON接口务必先toString()否则JSON.stringify会直接抛错const payload JSON.stringify({ count: count.toString() }); // 正确 // const payload JSON.stringify({ count }); // 会报TypeErrorpublic状态变量也同理。Counter合约里定义的count变量编译器会自动生成一个count()函数所以另一种读法是这样const countFromPublicVar await counter.count(); console.log(public变量读取:, countFromPublicVar.toString());两种写法读到的都是链上同一个值具体用哪个看你手上的ABI习惯。有些合约为了节省gas会把状态变量设为private那就只能靠合约提供的view函数来读。4.2 callStatic模拟执行写方法不花一分钱你可能会问我调用increment()这种写方法时Ethers.js会把一笔真实交易送上链。那如果我只是想知道这笔交易如果执行了会返回什么结果怎么办答案是用callStatic。它在本地节点里模拟执行这笔交易计算返回结果但不上链、不花钱。非常适合做前端提示、预测执行结果、参数校验这些场景。const wallet new Wallet(process.env.PRIVATE_KEY, provider); const writableCounter new Contract(contractAddress, abi, wallet); // 模拟执行incrementAndGet返回执行后的count但链上状态不变 const simulatedNewCount await writableCounter.callStatic.incrementAndGet(); console.log(模拟执行后的count:, simulatedNewCount.toString()); // 链上count仍然是原来的值 const realCount await writableCounter.getCount(); console.log(真实count:, realCount.toString());callStatic这个名字我第一次见时愣了一下其实它内部就是用eth_call代替eth_sendTransaction模拟执行一笔交易但不广播。注意它和estimateGas的区别estimateGas估算一笔交易要花多少gascallStatic得到的是函数返回值本身。两者都很常用但解决的问题完全不同。4.3 读历史事件queryFilter如果要看这个合约过去发生过哪些事件用queryFilter。比如Counter合约里每次调用increment都会emit一个Incremented事件// 查询从部署区块到最新高度的所有Incremented事件 const events await counter.queryFilter(Incremented, 0, latest); for (const event of events) { const by event.args.by; // 触发者地址 const newCount event.args.newCount; // 当时的新count值 console.log(区块 ${event.blockNumber}: ${by} increment 到 ${newCount.toString()}); }事件查询有三个关键参数事件名、起始区块、结束区块。起始区块必须给结束区块如果省略部分版本默认是latest。这里想提醒的是从0开始查一个很活跃的合约节点返回的数据量可能非常大甚至直接超时。更合理的做法是只查关心的时间段const events await counter.queryFilter(Incremented, deployBlock, deployBlock 5000);事件参数里如果用了indexed关键字它们在event.args里也能按字段名取出来。event.args其实是一个ArrayLike对象既可以按下标取event.args[0]也可以按名字取event.args.by都很方便。4.4 实时监听事件推送除了读历史Ethers.js还支持实时监听未来发生的事件。合约实例调用on()就能挂监听const listener async (by, newCount, event) { console.log(监听到Incremented:, by, newCount.toString()); // 处理完记得移除监听避免内存泄漏 counter.off(Incremented, listener); }; counter.on(Incremented, listener);on()回调的参数顺序和事件定义里参数顺序一致最后一个参数是事件载荷对象里面有交易哈希、区块号、日志索引等元信息。如果事件有indexed参数还可以只监听某个特定主题比如只关心某个地址触发的事件counter.on(counter.filters.Incremented(specificAddress), listener);这里filters.Incremented的第一个入参对应事件定义里by这个indexed参数。这种按主题过滤的监听方式在链上监控类项目里非常实用。比如你盯着一个资金池合约只想看某个用户的操作就可以用这个方式精准订阅不用在收到大量事件后自己再过滤一遍。4.5 populateTransaction与gas估算最后补充两个进阶但很常用的工具方法。一个是populateTransaction它不广播交易而是返回一笔交易的草稿让你能看到交易请求的具体内容——to、data、nonce等都在里面。这在调试、离线签名、或者要把交易转给第三方节点广播时非常有用const txRequest await writableCounter.incrementAndGet.populateTransaction(); console.log(txRequest); // 返回类似{ to: 0x..., data: 0x..., ... }另一个是estimateGas直接估算一笔写操作大概要消耗多少gasconst gasEstimate await writableCounter.incrementAndGet.estimateGas(); console.log(预计gas:, gasEstimate.toString());Ethers.js在发送交易时会自动估算gas但手动提前算一遍在批量操作或gas波动大的场景里能帮你把成本控制得更准。5. 发布和查询过程中最容易翻车的几个环节前面讲的是标准流程这一部分我想把真实环境里容易翻车的场景集中说一下。很多坑不踩一遍光看文档根本发现不了。5.1 地址校验与大小写格式以太坊地址有两种常见写法全小写和带校验和的混合大小写。Ethers.js对地址格式非常严格如果你从一个接口拿到全小写地址直接传给Contract构造函数可能会报invalid address。我遇到过一次这个报错一个第三方API返回的地址列表全是小写。解决办法是用ethers.getAddress统一转成checksum格式前置做一次校验const { getAddress, isAddress } require(ethers); if (!isAddress(rawAddress)) { throw new Error(非法地址: ${rawAddress}); } const checksummed getAddress(rawAddress);所有需要用户手工输入地址的地方先做这一步校验能挡掉一大半低级错误。5.2 部署成功但查询结果不对的完整排查链路有一次我帮同事排查问题现象是Counter合约部署成功了区块浏览器里也能看到合约代码但用Ethers.js调getCount()返回值是0而部署时构造函数明明传了100。我的排查过程是这样的。先让他把合约地址和部署交易哈希发给我我在区块浏览器上直接看合约状态发现合约里的count确实是100。说明合约本身没有错。接着让他把那行查询代码发我一眼就看出问题他new Contract时用的地址是对的但Provider连接的是以太坊主网的RPC而部署的合约在Sepolia测试网上。两个网络错位自然查不到状态。当时只要在代码里加一行验证就能发现const network await provider.getNetwork(); console.log(当前网络 chainId:, network.chainId);如果这行输出的chainId和你部署合约的网络对不上后面所有查询结果都没意义。我把查询结果不对这类问题的排查顺序整理一下按这个步骤走效率最高先用区块浏览器打开合约地址确认合约存在且状态正确。再检查代码里new Contract(address, abi, provider)的address是不是浏览器里那个地址。然后确认Provider连接的RPC网络和合约所在网络一致。最后确认查询的方法名拼写是否正确与ABI是否一致。大部分查询异常都出在这四步中的某一步而不是Ethers.js本身有问题。5.3 私钥与测试币管理的几个安全习惯开发阶段把私钥直接写在代码里确实方便但风险太大。即使只是本地脚本也建议用dotenv把它放到.env文件里并确保.gitignore包含.env// .env RPC_URLhttps://sepolia.infura.io/v3/你的KEY PRIVATE_KEY你的私钥// 脚本里 require(dotenv).config(); const wallet new Wallet(process.env.PRIVATE_KEY, provider);还有一个常见的开发期问题是测试币不够。部署和多次写操作会持续消耗测试币如果余额为0Ethers.js会抛insufficient funds或insufficient funds for gas * price value。第一次看到这个错误别慌去faucet领一些测试币再试就行。如果脚本连续发了好几笔交易第二笔报错还是insufficient funds检查一下第一笔交易是不是还没确认就把gas用完了。测试网虽然便宜但在短时间高频交易时gas管理一样要上心。5.4 交易一直pending的排查思路发起写操作后交易一直pending最常见的原因有三个gas给低了、节点不广播、nonce冲突。我的排查顺序一般是先在区块浏览器的pending区或节点工具里查这笔交易确认它是否真的被广播出去了。用provider.getTransaction(txHash)看交易详情检查gasPrice是否明显低于当前网络平均水平。如果gasPrice太低可以在发送时显式传入maxFeePerGas和maxPriorityFeePerGas覆盖默认值。如果交易已经广播但迟迟不确认又急着发下一笔先等当前这笔确认或者用同一nonce替换交易。这里想说句实话很多人一看pending就开始无脑重发结果把nonce搞乱反而让问题更复杂。正确做法是先观察再用区块浏览器确认交易状态最后才决定要不要干预。5.5 BigInt与JSON序列化的偶发问题再扩展讲一个前面提过的点。调用合约返回大数后如果直接塞进JSON.stringify会触发TypeError: Do not know how to serialize a BigInt。这个报错在你写服务端API、把合约数据返回给前端时非常容易碰到。我的习惯是从合约拿到的所有大数先统一toString()转成字符串再进行后续处理。如果你确实需要数值运算就保持bigint运算只在序列化边界做转换。一旦在项目里定下这个规矩序列化问题基本就绝迹了。如果你今天只打算记住一件事我希望是Provider和Signer的边界。Ethers.js的API再怎么变这个底层模型是不变的读数据永远找Provider写数据必须带上Signer。我在实际项目里见过的大多数部署失败和查询异常归根到底都绕不开这个逻辑。剩下的就是多写多试让报错把你训练成真正的调试选手。
Ethers.js v6智能合约部署与查询完整实战指南
做DApp开发的人迟早会遇到这么一件事Solidity合约在Remix里测试了一百遍都正常但要真正把它发布到链上再写个前端去查询合约状态轮到自己敲代码时却不知道从哪下手。我第一次用Ethers.js发布合约和查询合约就是这么熬过来的网上教程一搜一大把但版本多是Ethers.js v5照着敲下来要么报错要么拿不到合约地址折腾到后半夜才明白是API版本变了。这篇文章把我沉淀下来的完整流程和踩坑记录整理出来从环境准备到部署上链从只读查询到事件监听最后是一段真实排错过程全程用的都是Ethers.js这套库。如果你已经了解智能合约的基本概念正想用JavaScript或TypeScript和合约交互这篇文章可以直接照着抄。如果你连Provider和Signer是什么都还模糊也不用担心第二章节会把整个运行模型讲清楚后面的代码就不会只是背API了。1. 我为什么用Ethers.js做合约发布和查询1.1 Ethers.js与web3.js的取舍链上交互的JavaScript库其实不只Ethers.js一个老牌的web3.js用户基数也很大。我最早写链上脚本用的就是web3.js后来新项目全面切到Ethers.js之后最大的感受是省心。web3.js的API设计偏底层很多操作要自己组装请求。想发一笔普通交易得自己拼eth_gasPrice、eth_call、eth_sendTransaction这些RPC调用出错时错误信息也经常要你自己去翻JSON-RPC文档。Ethers.js在这层做了大量封装provider、wallet、contract全给你管好调用合约写方法时就像调用普通async函数gas估算、nonce管理、交易签名、等待确认这些琐碎逻辑都替你处理了。然后是数据类型。链上很多数据是uint256在JavaScript里超过Number.MAX_SAFE_INTEGER就会丢精度。web3.js旧版本返回数值经常要靠BN或BigNumber去转不同库的BigNumber还不兼容特别容易踩坑。Ethers.js从v5开始用BigNumberv6直接改用原生BigInt和JavaScript天然对齐IDE里类型提示也清晰得多。做过链上数据索引的人应该懂这里省下来的精力不是一点半点。另外从工程角度看Ethers.js的模块化做得更好按需引入时能利用Tree-shaking把最终打出来的包体积压得很小。对前端项目来说这点很有吸引力。而且Ethers.js的官方文档有大量代码示例很多疑问不需要去翻源码就能找到答案。1.2 v5与v6的差异怎么快速识别关于版本有个比较现实的建议直接学Ethers.js v6。现在搜索Ethers.js教程还能搜出一堆v5的代码但v6已经发布很久了API更干净文档也更整齐。很多网上v5代码直接拿来用会报错先认清这个事实能少走很多弯路。需要迁移的话重点看这几个差异场景v5写法v6写法连接RPCnew ethers.providers.JsonRpcProvider(url)new JsonRpcProvider(url)部署后等待上链await contract.deployed()await contract.waitForDeployment()获取合约地址contract.addresscontract.target返回大数ethers.BigNumber原生BigInt地址校验ethers.utils.getAddress(addr)ethers.getAddress(addr)错误处理需要手动解包直接用code和reason定位原因我见过不少项目还跑在v5上如果要长期维护迁移成本其实没想象中高。但如果是新项目直接v6就好。下面所有代码统一用v6写法。2. 发布前必须搞懂的三层角色模型很多新手卡在Ethers.js部署合约这一步不是因为代码难写而是没弄明白几个核心对象各管什么。花十分钟把这个模型搞清楚比背二十个API都有用。2.1 Provider读数据靠它Provider是连接区块链节点的通道负责跟节点通信帮我读链上的数据。比如查地址余额、看交易状态、拿当前区块高度都走Provider。它不持有任何私钥也没有身份的概念可以理解成一条只读的HTTP通道只要拿到一个RPC URL就能创建。const { JsonRpcProvider } require(ethers); const provider new JsonRpcProvider(process.env.RPC_URL);刚接触Ethers.js的人容易把Provider和节点混为一谈。其实Provider只是一个客户端抽象真正干活的是背后那个RPC节点。Ethers.js支持的Provider类型也不少JsonRpcProvider是主力浏览器里还会用BrowserProvider去接管钱包插件暴露的接口。2.2 Wallet与Signer写数据靠它Wallet管的是写。它由私钥派生而来负责给交易签名证明这笔交易确实是这个人发出的。Wallet本身不直接连区块链它需要挂一个Provider才能把签名后的交易广播出去。创建Wallet有两种常见姿势// 方式一助记词 const wallet Wallet.fromPhrase(process.env.MNEMONIC, provider); // 方式二私钥 const wallet new Wallet(process.env.PRIVATE_KEY, provider);Wallet是Signer的最常用实现。今后你在API文档里看到Signer这个词不要慌它的核心能力就是持有密钥并签名Wallet就是它在本地私钥场景下的具体形态。凡是涉及转ETH、部署合约、调合约写方法的场景都必须有Signer参与。2.3 Contract连接ABI与链上状态的代理Contract是读写都管的代理。把ABI传进去之后Ethers.js会把合约里的函数变成JS方法。view或pure类型的函数直接读链上数据非view的函数自动生成一笔交易由指定的Signer签名后广播。这里有一个很多新手漏掉的细节Contract实例绑定的第三个参数决定它能不能发起写操作。绑定Provider的实例只能做只读操作绑定Signer的才能发起写操作。用代码说明更直观const { JsonRpcProvider, Contract } require(ethers); const provider new JsonRpcProvider(process.env.RPC_URL); // 第三个参数传provider这个实例只能读 const readOnlyContract new Contract(contractAddress, abi, provider); // 读没问题 await readOnlyContract.getCount(); // 调用写方法就会报错因为实例没有signer await readOnlyContract.increment();反过来创建实例时第三个参数传walletconst { Wallet, Contract } require(ethers); const wallet new Wallet(process.env.PRIVATE_KEY, provider); // 有签名能力的合约实例 const writableContract new Contract(contractAddress, abi, wallet); // 写方法能正常发起交易了 const tx await writableContract.increment();把这三个角色边界记清楚后面无论部署还是查询本质都是在这三个对象之间倒腾。3. 从零开始发布一份合约完整走通部署链路部署合约本质上是把一份带构造函数参数的字节码用一笔交易发送到链上。Ethers.js把这一层封装得很舒服但有几个细节值得拆开看。3.1 拿到可部署的ABI和Bytecode很多人忽略这一点Ethers.js只会帮你广播合约不会替你编译Solidity。所以在调用部署方法之前必须先把Solidity源码编译成ABI和Bytecode并且确保这两样东西来自同一份源码。最常见的做法是用Hardhat或Foundry编译。以Hardhat为例编译产物在artifacts/contracts/Counter.sol/Counter.json这个JSON里就有abi和bytecode两个字段。脚本里直接加载const contractJSON require(./artifacts/contracts/Counter.sol/Counter.json); const { abi, bytecode } contractJSON;如果只是临时实验也可以从Remix的编译面板里复制ABI和Bytecode。但Bytecode非常长手抄极易出错推荐用自动加载的方式。为了方便后面演示我准备一个极简Counter合约带一个构造函数参数还额外放了一个有返回值的写函数后面讲callStatic时要用// SPDX-License-Identifier: MIT pragma solidity ^0.8.19; contract Counter { uint256 public count; event Incremented(address indexed by, uint256 newCount); constructor(uint256 initialCount) { count initialCount; } function increment() public { count 1; emit Incremented(msg.sender, count); } function incrementAndGet() public returns (uint256) { count 1; emit Incremented(msg.sender, count); return count; } function getCount() public view returns (uint256) { return count; } }这个合约公开的count变量会自动生成一个同名的view函数所以getCount()和count()读到的值一样。我两个都留着方便后面演示查询函数的两种方式。3.2 用ContractFactory发起部署拿到ABI和Bytecode以后部署的入口是ContractFactory。这个类名很形象它就是生产合约实例的工厂你把ABI、Bytecode、Signer交给它它帮你造出合约并部署。const { ContractFactory, Wallet, JsonRpcProvider } require(ethers); const provider new JsonRpcProvider(process.env.RPC_URL); const wallet new Wallet(process.env.PRIVATE_KEY, provider); const factory new ContractFactory(abi, bytecode, wallet); // 构造函数参数是100对应Counter构造函数的initialCount const contract await factory.deploy(100);这里要特别提醒factory.deploy()返回的是一个合约实例但此刻交易可能还没上链。也就是说contract.target这个地址在区块确认之前实际上是不存在的。所以下一步必须等交易真正确认再对外使用这个地址。3.3 等待交易上链并拿到合约地址v6里等待部署完成的函数是waitForDeployment()v5叫deployed()。这个差别非常典型// v6写法 await contract.waitForDeployment(); const contractAddress contract.target; const deployTxHash contract.deploymentTransaction().hash; console.log(部署交易哈希:, deployTxHash); console.log(合约地址:, contractAddress);contract.target就是新合约地址v5里它叫contract.address。拿到地址后强烈建议用Provider再验证一遍合约是否真的在链上const code await provider.getCode(contractAddress); console.log(链上代码长度:, code.length);如果合约部署成功code会是一串十六进制字节码长度肯定大于2。如果返回的是0x说明该地址上没有合约要么部署没成功要么查询的网络不对。这一步验证在自动化脚本里非常实用能帮你第一时间发现问题。3.4 部署交易的Gas与环境细节部署交易和普通交易一样要花gas而且合约构造和初始化的成本不低。Ethers.js默认会调用eth_estimateGas估算gas但有两种情况我建议手动指定gasLimit一是构造函数逻辑比较复杂估算可能不准二是你想把gasLimit固定下来避免因节点估算波动导致交易失败。const contract await factory.deploy(100, { gasLimit: 3000000, });另一个容易忽略的问题是网络选择。Sepolia是目前最常用的以太坊测试网之一RPC地址可以从Alchemy、Infura或公共节点获取。部署到测试网需要一个带测试ETH的账户去对应测试网的faucet领一点就够用Sepolia的faucet有时候会网络抽风多试几个渠道就行。拿到测试币后脚本跑完记得把合约地址和交易哈希记录下来。后面的查询全部依赖这个地址。4. 查询合约有哪些玩法只读调用、staticCall与事件读取合约部署完真正的使用才开始。查询合约通常指一整类读取链上状态的操作包括直接调用view函数、模拟执行写操作、读历史事件、实时监听事件。每种场景对应的API在Ethers.js里差别很大。4.1 只读方法直接调用链上合约的view和pure函数不会改变状态所以Ethers.js生成的调用直接走eth_call不消耗gas也就是常说的免费查询。只要合约地址和ABI正确任何人都能读const { JsonRpcProvider, Contract } require(ethers); const provider new JsonRpcProvider(process.env.RPC_URL); const counter new Contract(contractAddress, abi, provider); const count await counter.getCount(); console.log(当前计数值:, count.toString());这里有个新手很容易忽略的点在Ethers.js v6里合约函数返回的uint256是JavaScript的bigint类型不是number。直接打印它时末尾会带个n比如100n。直接做运算没问题但如果要拼进字符串或传给JSON接口务必先toString()否则JSON.stringify会直接抛错const payload JSON.stringify({ count: count.toString() }); // 正确 // const payload JSON.stringify({ count }); // 会报TypeErrorpublic状态变量也同理。Counter合约里定义的count变量编译器会自动生成一个count()函数所以另一种读法是这样const countFromPublicVar await counter.count(); console.log(public变量读取:, countFromPublicVar.toString());两种写法读到的都是链上同一个值具体用哪个看你手上的ABI习惯。有些合约为了节省gas会把状态变量设为private那就只能靠合约提供的view函数来读。4.2 callStatic模拟执行写方法不花一分钱你可能会问我调用increment()这种写方法时Ethers.js会把一笔真实交易送上链。那如果我只是想知道这笔交易如果执行了会返回什么结果怎么办答案是用callStatic。它在本地节点里模拟执行这笔交易计算返回结果但不上链、不花钱。非常适合做前端提示、预测执行结果、参数校验这些场景。const wallet new Wallet(process.env.PRIVATE_KEY, provider); const writableCounter new Contract(contractAddress, abi, wallet); // 模拟执行incrementAndGet返回执行后的count但链上状态不变 const simulatedNewCount await writableCounter.callStatic.incrementAndGet(); console.log(模拟执行后的count:, simulatedNewCount.toString()); // 链上count仍然是原来的值 const realCount await writableCounter.getCount(); console.log(真实count:, realCount.toString());callStatic这个名字我第一次见时愣了一下其实它内部就是用eth_call代替eth_sendTransaction模拟执行一笔交易但不广播。注意它和estimateGas的区别estimateGas估算一笔交易要花多少gascallStatic得到的是函数返回值本身。两者都很常用但解决的问题完全不同。4.3 读历史事件queryFilter如果要看这个合约过去发生过哪些事件用queryFilter。比如Counter合约里每次调用increment都会emit一个Incremented事件// 查询从部署区块到最新高度的所有Incremented事件 const events await counter.queryFilter(Incremented, 0, latest); for (const event of events) { const by event.args.by; // 触发者地址 const newCount event.args.newCount; // 当时的新count值 console.log(区块 ${event.blockNumber}: ${by} increment 到 ${newCount.toString()}); }事件查询有三个关键参数事件名、起始区块、结束区块。起始区块必须给结束区块如果省略部分版本默认是latest。这里想提醒的是从0开始查一个很活跃的合约节点返回的数据量可能非常大甚至直接超时。更合理的做法是只查关心的时间段const events await counter.queryFilter(Incremented, deployBlock, deployBlock 5000);事件参数里如果用了indexed关键字它们在event.args里也能按字段名取出来。event.args其实是一个ArrayLike对象既可以按下标取event.args[0]也可以按名字取event.args.by都很方便。4.4 实时监听事件推送除了读历史Ethers.js还支持实时监听未来发生的事件。合约实例调用on()就能挂监听const listener async (by, newCount, event) { console.log(监听到Incremented:, by, newCount.toString()); // 处理完记得移除监听避免内存泄漏 counter.off(Incremented, listener); }; counter.on(Incremented, listener);on()回调的参数顺序和事件定义里参数顺序一致最后一个参数是事件载荷对象里面有交易哈希、区块号、日志索引等元信息。如果事件有indexed参数还可以只监听某个特定主题比如只关心某个地址触发的事件counter.on(counter.filters.Incremented(specificAddress), listener);这里filters.Incremented的第一个入参对应事件定义里by这个indexed参数。这种按主题过滤的监听方式在链上监控类项目里非常实用。比如你盯着一个资金池合约只想看某个用户的操作就可以用这个方式精准订阅不用在收到大量事件后自己再过滤一遍。4.5 populateTransaction与gas估算最后补充两个进阶但很常用的工具方法。一个是populateTransaction它不广播交易而是返回一笔交易的草稿让你能看到交易请求的具体内容——to、data、nonce等都在里面。这在调试、离线签名、或者要把交易转给第三方节点广播时非常有用const txRequest await writableCounter.incrementAndGet.populateTransaction(); console.log(txRequest); // 返回类似{ to: 0x..., data: 0x..., ... }另一个是estimateGas直接估算一笔写操作大概要消耗多少gasconst gasEstimate await writableCounter.incrementAndGet.estimateGas(); console.log(预计gas:, gasEstimate.toString());Ethers.js在发送交易时会自动估算gas但手动提前算一遍在批量操作或gas波动大的场景里能帮你把成本控制得更准。5. 发布和查询过程中最容易翻车的几个环节前面讲的是标准流程这一部分我想把真实环境里容易翻车的场景集中说一下。很多坑不踩一遍光看文档根本发现不了。5.1 地址校验与大小写格式以太坊地址有两种常见写法全小写和带校验和的混合大小写。Ethers.js对地址格式非常严格如果你从一个接口拿到全小写地址直接传给Contract构造函数可能会报invalid address。我遇到过一次这个报错一个第三方API返回的地址列表全是小写。解决办法是用ethers.getAddress统一转成checksum格式前置做一次校验const { getAddress, isAddress } require(ethers); if (!isAddress(rawAddress)) { throw new Error(非法地址: ${rawAddress}); } const checksummed getAddress(rawAddress);所有需要用户手工输入地址的地方先做这一步校验能挡掉一大半低级错误。5.2 部署成功但查询结果不对的完整排查链路有一次我帮同事排查问题现象是Counter合约部署成功了区块浏览器里也能看到合约代码但用Ethers.js调getCount()返回值是0而部署时构造函数明明传了100。我的排查过程是这样的。先让他把合约地址和部署交易哈希发给我我在区块浏览器上直接看合约状态发现合约里的count确实是100。说明合约本身没有错。接着让他把那行查询代码发我一眼就看出问题他new Contract时用的地址是对的但Provider连接的是以太坊主网的RPC而部署的合约在Sepolia测试网上。两个网络错位自然查不到状态。当时只要在代码里加一行验证就能发现const network await provider.getNetwork(); console.log(当前网络 chainId:, network.chainId);如果这行输出的chainId和你部署合约的网络对不上后面所有查询结果都没意义。我把查询结果不对这类问题的排查顺序整理一下按这个步骤走效率最高先用区块浏览器打开合约地址确认合约存在且状态正确。再检查代码里new Contract(address, abi, provider)的address是不是浏览器里那个地址。然后确认Provider连接的RPC网络和合约所在网络一致。最后确认查询的方法名拼写是否正确与ABI是否一致。大部分查询异常都出在这四步中的某一步而不是Ethers.js本身有问题。5.3 私钥与测试币管理的几个安全习惯开发阶段把私钥直接写在代码里确实方便但风险太大。即使只是本地脚本也建议用dotenv把它放到.env文件里并确保.gitignore包含.env// .env RPC_URLhttps://sepolia.infura.io/v3/你的KEY PRIVATE_KEY你的私钥// 脚本里 require(dotenv).config(); const wallet new Wallet(process.env.PRIVATE_KEY, provider);还有一个常见的开发期问题是测试币不够。部署和多次写操作会持续消耗测试币如果余额为0Ethers.js会抛insufficient funds或insufficient funds for gas * price value。第一次看到这个错误别慌去faucet领一些测试币再试就行。如果脚本连续发了好几笔交易第二笔报错还是insufficient funds检查一下第一笔交易是不是还没确认就把gas用完了。测试网虽然便宜但在短时间高频交易时gas管理一样要上心。5.4 交易一直pending的排查思路发起写操作后交易一直pending最常见的原因有三个gas给低了、节点不广播、nonce冲突。我的排查顺序一般是先在区块浏览器的pending区或节点工具里查这笔交易确认它是否真的被广播出去了。用provider.getTransaction(txHash)看交易详情检查gasPrice是否明显低于当前网络平均水平。如果gasPrice太低可以在发送时显式传入maxFeePerGas和maxPriorityFeePerGas覆盖默认值。如果交易已经广播但迟迟不确认又急着发下一笔先等当前这笔确认或者用同一nonce替换交易。这里想说句实话很多人一看pending就开始无脑重发结果把nonce搞乱反而让问题更复杂。正确做法是先观察再用区块浏览器确认交易状态最后才决定要不要干预。5.5 BigInt与JSON序列化的偶发问题再扩展讲一个前面提过的点。调用合约返回大数后如果直接塞进JSON.stringify会触发TypeError: Do not know how to serialize a BigInt。这个报错在你写服务端API、把合约数据返回给前端时非常容易碰到。我的习惯是从合约拿到的所有大数先统一toString()转成字符串再进行后续处理。如果你确实需要数值运算就保持bigint运算只在序列化边界做转换。一旦在项目里定下这个规矩序列化问题基本就绝迹了。如果你今天只打算记住一件事我希望是Provider和Signer的边界。Ethers.js的API再怎么变这个底层模型是不变的读数据永远找Provider写数据必须带上Signer。我在实际项目里见过的大多数部署失败和查询异常归根到底都绕不开这个逻辑。剩下的就是多写多试让报错把你训练成真正的调试选手。
