solidity-hardhat-development

Hardhat 3 开发指南

适用场景

• 启动新的 Hardhat 3 项目。
• 从 v2 迁移到 v3。
• 使用兼容 Foundry 的测试测试 Solidity 合约。
• 使用 Hardhat Ignition 部署。
• 构建多链应用。

要求

要求	值
Node.js	v22.10 或更高版本
模块系统	ESM — 在 package.json 中设置 "type": "module"
初始化命令	npx hardhat --init
配置入口	hardhat/config 中的 defineConfig

配置

使用 solidity、networks 和 plugins 键组织设置。使用 configVariable("KEY") 存储密钥，避免将其写入代码。必须显式列出插件——v2 中的副作用导入不再有效。

网络 type	用途
edr-simulated	本地进程内测试
http	远程 RPC 连接

chainType 接受 "l1"、"op" 或 "generic"。构建配置文件允许为不同环境设置参数（例如，为生产环境启用优化器）。

import { defineConfig, configVariable } from "hardhat/config";
import { hardhatIgnition } from "@nomicfoundation/hardhat-ignition";

export default defineConfig({
  solidity: "0.8.28",
  plugins: [hardhatIgnition],
  networks: {
    hardhat: { type: "edr-simulated" },
    mainnet: { type: "http", url: configVariable("MAINNET_RPC_URL") },
  },
});

测试

测试类型	运行器	备注
Solidity（.t.sol）	Rust 驱动	继承 forge-std/Test.sol；支持完整的 vm 欺骗码；内置模糊测试
TypeScript	Node 测试运行器 + Viem，或 Mocha + Ethers	通过 networkHelpers 属性访问网络辅助工具

命令	运行内容
npx hardhat test	所有测试
npx hardhat test solidity	仅 Solidity 测试
--coverage	覆盖率数据
--gas-stats	Gas 使用数据

部署（Ignition）

Hardhat Ignition 是主要的部署框架：通过 buildModule 声明式定义模块、自动并行化交易，并自动恢复失败的部署。

• 部署：npx hardhat ignition deploy ignition/modules/MyModule.ts --network <network>
• 验证：@nomicfoundation/hardhat-verify 插件

多链支持

Hardhat 3 可同时模拟多条链。使用 const mainnet = await network.connect("mainnet") 按网络连接。可同时分叉多条链，以进行复杂的跨链测试。

调试

工具	用途
console.log（hardhat/console.sol）	在合约内部打印调试信息
test 命令的详细程度标志	增加跟踪信息的详细程度
EDR 堆栈跟踪	详细的故障跟踪

从 v2 迁移

v2	v3
CommonJS	ESM（"type": "module"）
Node.js < 22	Node.js v22.10+
module.exports	defineConfig
副作用插件导入	显式的 plugins 数组
Ethers v5	Ethers v6 或 Viem
单一网络对象	多链 NetworkManager
v2 插件	v3 专用插件版本

必备插件：hardhat-verify、hardhat-ignition、hardhat-keystore。

通过 MCP 增强

当 solidity-agent-toolkit 可用时：

• compile_contract：构建合约并获取产物。
• run_tests：运行测试套件。
• gas_snapshot：获取 Gas 报告。
• dry_run_deploy：模拟部署。
• run_slither、run_aderyn：执行安全分析。

参考资料

示例请参阅 Hardhat 3 速查表。