Hardhat部署迁移指南：从旧版本到最新生态的平滑升级路径

Hardhat 工具链经过几次大幅迭代，存量项目升级时常常被一堆 API 变更绊住。本文围绕 Hardhat部署迁移指南的核心议题，给出一份可执行的升级清单，每一步都附带验证方法，让迁移过程可控、可回滚。最新版本能力概览见 Hardhat部署最新版本。

一、迁移前的评估

在动手前先回答几个问题：

• 当前 Hardhat 版本与目标版本之间相差几个大版本
• 项目依赖 ethers v5 还是 v6
• 是否在用 hardhat-deploy、@openzeppelin/hardhat-upgrades 等插件
• 部署脚本中是否有大量 BN.js 风格代码

这些回答决定了迁移的难度与时间预算。建议把现状写成一份 RFC，团队 review 后再开工。

二、升级 Hardhat 主包

第一步只升 Hardhat 主包，保留脚本不动：

• pnpm up hardhat@latest
• 跑 npx hardhat compile、npx hardhat test、npx hardhat run scripts/deploy.ts --network localhost
• 把所有 deprecation 警告记录下来逐条处理

这一步保证基础功能没坏，是后续动作的安全网。配合 Hardhat更新内容 阅读，能更快定位需要修改的地方。

三、ethers v5 到 v6 迁移

核心变化：

• BigNumber 替换为原生 BigInt
• Contract.deploy() 改为 ethers.deployContract()
• signer.connect(provider) 等 API 略调整
• 事件解析的 parseLog 返回类型变化

建议按文件迁移：先把工具函数迁完，再迁部署脚本，最后迁测试。每个文件迁完跑一次单测，避免一次性改太多无法定位问题。这一过程的细节在 Hardhat迁移指南 通用版本中也有详细描述。

四、插件整合

推荐用 @nomicfoundation/hardhat-toolbox 一次性引入 ethers、chai-matchers、verify、coverage、gas-reporter 等常用插件：

• 移除原本零散的 hardhat-ethers、hardhat-waffle 等单独依赖
• hardhat.config.ts 顶部 import '@nomicfoundation/hardhat-toolbox' 即可
• 保持依赖收敛，未来升级只需关心 toolbox 版本

五、考虑切换到 hardhat-ignition

ignition 是新一代部署框架：

• 用 module 描述部署关系
• 自动处理依赖与初始化
• 内置失败重试与状态恢复
• 输出干净的 deployments 记录

如果你的项目部署逻辑复杂（多合约、多步骤），切换 ignition 能显著降低脚本维护成本。这一变化在 Hardhat部署进阶教程 中也被列为重点方向。

六、Verify 配置迁移

Verify 部分的变化：

• etherscan.apiKey 推荐写成对象而非字符串
• customChains 字段支持多链
• 失败重试机制更稳定

迁移后第一时间跑一次 verify，确认所有链都能成功。币安智能链上 customChains 写法略特殊，可参考 Hardhat部署中文文档 中的范例。

七、CI 与 Secrets 调整

升级后建议同步调整 CI：

• 锁定 Node 18 或 20 版本
• 重新生成 lockfile 并提交
• 检查 Secrets 中是否还引用了已废弃的环境变量
• 部署测试用 CI 跑一次完整流程

八、上线后回归测试

迁移完成后必须跑一遍回归：

• 在测试网完整部署一次
• 调用核心读写方法
• 跑 Verify 与 Gas reporter
• 与上一版本对比 Gas 消耗，差异过大需排查

按上述八步完成迁移后，你的项目就完整切换到了最新生态。迁移的关键不是「快」，而是「每一步可回滚」。把每个步骤独立提交、独立验证，整个过程就能在数天内完成而不影响生产部署。