Hardhat 项目开发环境搭建完整指南

1. 从 GitHub 下载项目

# 使用 SSH 方式克隆（需要配置 SSH key）
git clone git@github.com:NomicFoundation/hardhat.git

# 或使用 HTTPS 方式
git clone https://github.com/NomicFoundation/hardhat.git

# 进入项目目录
cd hardhat

2. 判断项目包管理器类型

判断依据和方法

# 方法1：查看锁文件
ls -la | grep -E "pnpm-lock|yarn.lock|package-lock"

判断标准：

• 存在 pnpm-lock.yaml → 使用 pnpm
• 存在 yarn.lock → 使用 yarn
• 存在 package-lock.json → 使用 npm

# 方法2：查看 package.json 中的 packageManager 字段
cat package.json | grep packageManager

# 方法3：查看是否有 workspace 配置文件
ls -la | grep -E "pnpm-workspace.yaml|lerna.json"

Hardhat 项目特征：

• ✅ 存在 pnpm-workspace.yaml 文件
• ✅ package.json 中 "private": true
• ✅ 使用递归命令 pnpm run --recursive
• 结论：Hardhat 使用 pnpm 作为包管理器

安装对应的包管理器

# 安装 pnpm（如果没有）
npm install -g pnpm

# 验证安装
pnpm --version

3. 下载依赖

# 使用 pnpm 安装依赖（Hardhat 推荐）
pnpm install

# 如果遇到网络问题，使用国内镜像
pnpm config set registry https://registry.npmmirror.com
pnpm install

# 如果有构建脚本警告
pnpm approve-builds  # 审批需要运行的构建脚本

常见问题解决：

# 如果提示包找不到或 404 错误
pnpm install --no-frozen-lockfile

# 如果有缓存问题
pnpm store prune
pnpm install

4. 编译项目

# 构建所有包
pnpm build

# 如果构建时间过长，可以构建特定包
pnpm --filter hardhat-core build
pnpm --filter hardhat-ethers build

# 查看所有可构建的包
pnpm ls -r --depth=0

构建顺序建议：

1. 先构建核心包：pnpm --filter hardhat-core build
2. 再构建依赖它的包：pnpm build

5. 运行测试文件

# 运行所有测试
pnpm test

# 运行特定包的测试
pnpm --filter hardhat-core test

# 带详细输出的测试
pnpm test --stream

# 设置超时（避免卡住）
pnpm test -- --timeout 10000

# 跳过慢速测试
SKIP_SLOW_TESTS=true pnpm test

# 只运行特定测试
pnpm test -- --grep "specific test name"

测试卡住的解决方法：

# 1. 中断测试 (Ctrl+C)

# 2. 跳过编译器下载测试
pnpm test -- --grep "compiler" --invert

# 3. 只测试你修改的部分
pnpm --filter <package-name> test

6. 重新下载编译（清理并重建）

完整清理脚本

#!/bin/bash
# clean-rebuild.sh

echo "🧹 开始清理..."

# 1. 清理所有 node_modules
find . -name "node_modules" -type d -prune -exec rm -rf {} \; 2>/dev/null

# 2. 清理构建产物
find . -name "dist" -type d -prune -exec rm -rf {} \; 2>/dev/null
find . -name "build" -type d -prune -exec rm -rf {} \; 2>/dev/null
find . -name "*.tsbuildinfo" -type f -delete 2>/dev/null

# 3. 清理缓存
rm -rf .cache
rm -rf coverage
rm -rf .nyc_output

# 4. 清理锁文件（可选）
# rm -f pnpm-lock.yaml

# 5. 清理 pnpm 存储
pnpm store prune

echo "📦 重新安装依赖..."
pnpm install

echo "🔨 重新构建..."
pnpm build

echo "✅ 完成！"

使用方法：

chmod +x clean-rebuild.sh
./clean-rebuild.sh

快速清理命令

# 清理并重建
pnpm clean && pnpm install && pnpm build

# 只清理 node_modules
rm -rf node_modules packages/*/node_modules v-next/*/node_modules

# 只清理构建产物
pnpm clean

7. 解决文件引入爆红问题

问题原因

TypeScript 配置文件未生效，VS Code 未正确识别项目结构。

解决方法

方法1：保存配置文件触发重载

# 找到并重新保存这些文件（触发 VS Code 重新加载）
touch tsconfig.json
touch tsconfig.base.json
touch packages/*/tsconfig.json

方法2：重启 TypeScript 服务

1. 在 VS Code 中按 Ctrl+Shift+P
2. 输入 “TypeScript: Restart TS Server”
3. 回车执行

方法3：修复 TypeScript 配置

# 创建/更新基础配置
cat > tsconfig.base.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "baseUrl": ".",
    "types": ["node"]
  }
}
EOF

# 重新打开文件或重启 VS Code

方法4：VS Code 工作区设置

# 创建 VS Code 配置
mkdir -p .vscode
cat > .vscode/settings.json << 'EOF'
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}
EOF

8. Hardhat 目录结构说明

核心目录结构

hardhat/
├── packages/                  # 📦 核心包目录（monorepo 结构）
│   ├── hardhat-core/         # 🎯 Hardhat 核心功能
│   │   ├── src/             # 源代码
│   │   │   ├── builtin-tasks/  # 内置任务（compile, test, run等）
│   │   │   ├── internal/       # 内部实现
│   │   │   └── types/          # TypeScript 类型定义
│   │   └── test/            # 测试文件
│   │
│   ├── hardhat-ethers/       # 🔗 Ethers.js 集成插件
│   ├── hardhat-web3/         # 🌐 Web3.js 集成插件
│   ├── hardhat-waffle/       # 🧪 Waffle 测试框架集成
│   ├── hardhat-truffle5/     # 🔄 Truffle 兼容层
│   ├── hardhat-vyper/        # 🐍 Vyper 编译器支持
│   ├── hardhat-solhint/      # 📝 Solhint 代码检查
│   ├── hardhat-network-helpers/ # 🛠️ 网络辅助工具
│   └── hardhat-toolbox/      # 🧰 常用工具集合包
│
├── v-next/                    # 🚀 下一版本开发目录
│   ├── hardhat/              # 新版本核心
│   └── hardhat-verify/       # 合约验证功能
│
├── config/                    # ⚙️ 项目配置文件
│   └── eslint/              # ESLint 配置
│
├── docs/                      # 📚 文档
│
├── scripts/                   # 🔧 构建和维护脚本
│
├── .changeset/               # 📝 版本变更记录（用于发布）
│
├── .github/                  # 🐙 GitHub 配置
│   └── workflows/           # CI/CD 工作流
│
├── pnpm-workspace.yaml       # 📦 pnpm 工作空间配置
├── package.json              # 📋 根项目配置
├── tsconfig.json            # 🔷 TypeScript 配置
└── README.md                # 📖 项目说明

各目录详细说明

packages/ - 核心包集合

• 作用：包含所有 Hardhat 官方包和插件
• 特点：每个子目录都是独立的 npm 包，可单独发布
• 开发：新功能通常在这里添加

packages/hardhat-core/

• 作用：Hardhat 的核心引擎
• 包含：
  • 任务系统
  • 配置管理
  • 插件系统
  • Hardhat Network（内置 EVM）
  • 编译器管理

v-next/

• 作用：下一个主要版本的开发目录
• 特点：实验性功能，可能有破坏性变更

config/

• 作用：共享配置文件
• 内容：ESLint、Prettier、TypeScript 基础配置

scripts/

• 作用：项目维护脚本
• 包含：
  • 构建脚本
  • 发布脚本
  • 代码生成工具

.changeset/

• 作用：管理版本变更和发布
• 工作流：

  pnpm changeset  # 创建变更记录
  pnpm version-packages  # 更新版本
  pnpm release  # 发布到 npm
  

开发新功能的位置选择

注意：这个项目主要在 v-next/ 目录下开发，而不是 packages/ 目录。

1. 添加新功能 → v-next/ 下选择合适的包或创建新包
2. 查看现有包 → ls -la v-next/ 查看 28 个现有包
3. 创建新插件 → 在 v-next/ 下创建新目录
4. 修改核心功能 → v-next/hardhat/
5. 添加验证功能 → v-next/hardhat-verify/

查看 v-next 包列表

# 查看所有 v-next 下的包
ls -la v-next/

# 统计包数量
ls -1 v-next/ | wc -l  # 应该显示 28

# 查看每个包的 package.json
for dir in v-next/*/; do
  echo "=== $(basename $dir) ==="
  cat "$dir/package.json" | grep '"name"' 2>/dev/null
done

快速开始开发

# 1. 克隆并进入项目
git clone git@github.com:NomicFoundation/hardhat.git
cd hardhat

# 2. 安装依赖
pnpm install

# 3. 构建项目
pnpm build

# 4. 开始开发
# 修改代码...

# 5. 测试修改
pnpm test

# 6. 创建变更记录（准备发布）
pnpm changeset

常用命令速查

# 依赖管理
pnpm install              # 安装依赖
pnpm add <package>        # 添加新依赖
pnpm remove <package>     # 移除依赖

# 构建
pnpm build               # 构建所有包
pnpm clean               # 清理构建产物
pnpm --filter <pkg> build # 构建特定包

# 测试
pnpm test                # 运行所有测试
pnpm test -- --watch     # 监听模式
pnpm --filter <pkg> test # 测试特定包

# 代码质量
pnpm lint                # 运行 lint
pnpm lint:fix            # 自动修复 lint 问题

# 版本管理
pnpm changeset           # 创建变更记录
pnpm version-packages    # 更新版本号

故障排除

问题	解决方法
依赖安装失败	pnpm install --no-frozen-lockfile
构建失败	先清理：pnpm clean 再构建
测试卡住	使用 Ctrl+C 中断，跳过慢速测试
TypeScript 错误	重启 TS Server 或重新保存 tsconfig.json
内存不足	NODE_OPTIONS="--max-old-space-size=4096" pnpm build

---

提示：这是一个 monorepo 项目，理解其结构对开发很重要。建议先熟悉 pnpm workspaces 的概念。