10分钟智能合约：进阶实战-5.2 Hardhat 开发环境搭建

Rockbean
57 阅读5分钟

欢迎订阅专栏：10分钟智能合约：进阶实战

本教程将带你从零开始，搭建一套专业、高效的 Hardhat 智能合约开发环境，并配合 VSCode 实现代码高亮、格式化、测试等完整功能。

一、为什么选择 Hardhat？

Hardhat 是目前以太坊生态最流行的智能合约开发框架。它集成了编译、测试、部署、调试四大核心功能，内置本地网络，支持插件扩展，是入门和专业开发者的共同选择。 hardhat.org/

image.png

二、基础环境准备

1. 安装 Node.js

访问 Node.js 官网，下载并安装 最新的 LTS（长期支持）版本。安装完成后，打开命令行工具验证：

node --version   # 应显示 v18.x.x 或更高
npm --version    # 应显示 9.x.x 或更高

2. 创建项目目录

mkdir my-hardhat-project
cd my-hardhat-project

3. 初始化 npm 项目

npm init -y

-y 参数会使用默认配置快速生成 package.json 文件。

三、安装并初始化 Hardhat

1. 安装 Hardhat（项目本地依赖）

npm install --save-dev hardhat

为什么本地安装？
将 Hardhat 作为项目开发依赖安装，可以避免不同项目间的版本冲突，并且更容易复现环境。

2. 初始化 Hardhat 项目结构

运行向导，生成示例合约、测试和部署脚本：

npx hardhat init

你会看到一个选项菜单，对于初学者，选择 “Create a JavaScript project”（或 TypeScript 项目）。一路回车确认后，项目结构将自动生成：

my-hardhat-project/
├── contracts/           # 智能合约源代码 (.sol)
├── ignition/modules/    # 部署脚本
├── test/                # 测试文件 (.js / .ts)
├── hardhat.config.js    # 核心配置文件
└── package.json

3. 验证是否安装成功

npx hardhat compile   # 编译示例合约
npx hardhat test      # 运行示例测试

如果看到编译成功和测试通过的输出，说明环境已就绪。

四、核心配置文件（hardhat.config.js）

初始生成的配置文件内容如下：

/** @type import('hardhat/config').HardhatUserConfig */
module.exports = {
  solidity: "0.8.28",
};

后续当你需要添加网络（如 Sepolia 测试网）、安装插件（如 hardhat-toolbox）或修改 Solidity 版本时，所有的改动都在这个文件里进行。

示例：添加测试网配置（可选）

如果要部署到 Sepolia 测试网，先安装 dotenv 管理私钥：

npm install --save-dev dotenv

然后在项目根目录创建 .env 文件：

SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/你的项目ID
PRIVATE_KEY=你的钱包私钥（不要提交到代码仓库！）

最后修改 hardhat.config.js：

require("@nomicfoundation/hardhat-toolbox");
require("dotenv").config();

module.exports = {
  solidity: "0.8.28",
  networks: {
    sepolia: {
      url: process.env.SEPOLIA_RPC_URL,
      accounts: [process.env.PRIVATE_KEY],
    },
  },
};

五、Visual Studio Code 开发环境搭配

为了获得语法高亮、智能提示、格式化、测试集成等开发体验，推荐使用 VSCode + 专用插件。

1. 安装插件（二选一）

image.png

插件名称开发者特点
SolidityJuan Blanco老牌插件，功能全面，支持多框架
SolidityNomic FoundationHardhat 官方团队维护，深度集成 Hardhat

推荐初学者使用 Hardhat 官方插件，与框架贴合度更高。 iShot_2026-06-15_23.08.08.png

2. 解决三个常见坑点

✅ 绑定文件语言模式

打开 .sol 文件后，如果右下角显示 “Plain Text”，点击它，在弹出的列表中选择 Solidity。
为了防止每次手动切换，可以在 VSCode 设置（settings.json）中添加：

"files.associations": {
    "*.sol": "solidity"
}

✅ SPDX 许可证声明

每个 Solidity 文件的第一行必须包含许可证声明，例如：

// SPDX-License-Identifier: MIT

缺失该声明会导致编译直接失败。

✅ 使用本地 Hardhat

确保 VSCode 的终端已经进入项目根目录（能看到 hardhat.config.js）。运行编译命令时，使用 npx hardhat compile，而不是 hardhat compile。

3. 代码格式化（Prettier）

安装格式化工具及 Solidity 插件：

npm install --save-dev prettier prettier-plugin-solidity

在项目根目录创建 .prettierrc 文件：

{
  "plugins": ["prettier-plugin-solidity"]
}

格式化操作：

  • 使用快捷键 Shift+Alt+F
  • 如果提示选择默认格式化程序，选择 Hardhat + Solidity（或 Prettier）

4. 运行测试集成

Hardhat 使用 Mocha 测试框架。若要在 VSCode 左侧直接运行测试，可以安装 Mocha Test Explorer 扩展，并在项目根目录创建 .mocharc.json：

{
  "require": "hardhat/register",
  "timeout": 40000
}

之后在 VSCode 的测试面板中即可一键执行所有测试。

六、开发工作流速查

操作命令
编译合约npx hardhat compile
运行测试npx hardhat test
启动本地节点npx hardhat node
部署到本地网络npx hardhat ignition deploy ./ignition/modules/YourModule.js --network localhost

七、常见问题与解决

问题现象可能原因解决方法
编译时报 SPDX license identifier not provided文件首行缺少许可证声明在文件第一行添加 // SPDX-License-Identifier: MIT
VSCode 中 Solidity 代码无高亮语言模式未正确识别手动设置为 Solidity，或配置 files.associations
npx hardhat compile 找不到命令未在项目根目录执行，或 Hardhat 未安装进入项目目录，重新执行 npm install --save-dev hardhat
格式化不生效缺少 Prettier 或 Solidity 插件安装 prettier 和 prettier-plugin-solidity，并添加 .prettierrc

八、总结

至此，你已经完成了 Hardhat 开发环境的完整搭建，并配置好了 VSCode 编辑器。你拥有：

  • 一个可编译、测试、部署的 Hardhat 项目。
  • 代码高亮、格式化、测试集成的现代化编辑器。
  • 可随时扩展到测试网或主网的配置文件。

接下来，你可以开始编写自己的智能合约了。建议从简单的 ERC-20 代币或 NFT 合约入手，并使用 npx hardhat test 编写测试用例，逐步深入。

下一步推荐阅读：

如果你在搭建过程中遇到任何问题，欢迎在评论区留言交流。

avatar
文章
阅读
粉丝