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 的概念。
)
)
