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
构建顺序建议：
- 先构建核心包：
pnpm --filter hardhat-core build - 再构建依赖它的包：
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.shecho "🧹 开始清理..."# 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 pruneecho "📦 重新安装依赖..."
pnpm installecho "🔨 重新构建..."
pnpm buildecho "✅ 完成！"
使用方法：
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 服务
- 在 VS Code 中按
Ctrl+Shift+P - 输入 “TypeScript: Restart TS Server”
- 回车执行
方法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/ 目录。
- 添加新功能 →
v-next/下选择合适的包或创建新包 - 查看现有包 →
ls -la v-next/查看 28 个现有包 - 创建新插件 → 在
v-next/下创建新目录 - 修改核心功能 →
v-next/hardhat/ - 添加验证功能 →
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/*/; doecho "=== $(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 的概念。
)
)
