智能合约与以太坊 / 系统课时
初始化 Foundry 工程和测试目录
初始化 Foundry 工程和测试目录
本课将从零搭建一个可编译、可运行测试的 Foundry 工程。完成后,你将能够使用 Forge 管理 Solidity 合约,识别源码、测试、脚本与依赖目录,并通过实际编译和测试确认环境正常,为后续模糊测试准备可靠的工程基线。
学习目标
- 安装并验证 Foundry 工具链,使用 Forge 初始化 Solidity 工程。
- 理解
src、test、script、lib和foundry.toml的职责。 - 运行编译与测试命令,定位常见的工具链和依赖问题。
安装 Foundry 并确认工具链
Foundry 是面向以太坊智能合约开发的工具集,主要包含四个命令行工具:
| 工具 | 用途 | 常见命令 |
|---|---|---|
| Forge | 编译、测试和部署合约 | forge build、forge test |
| Cast | 调用合约、查询链上数据 | cast --version |
| Anvil | 启动本地以太坊开发节点 | anvil --version |
| Chisel | 交互式 Solidity 开发环境 | chisel --version |
以下操作适用于 macOS、Linux 和 Windows 的 WSL2 环境。Windows 用户建议在 WSL2 的 Ubuntu 终端中执行,不要直接将这些 Bash 安装命令复制到 PowerShell。
首先确认终端中可以使用 Git 和 curl:
git --version
curl --version预期结果:两条命令分别输出 Git 和 curl 的版本信息,具体版本号因环境而异。
接着安装官方的 Foundryup 安装器:
# 下载并运行 Foundry 官方安装脚本
curl -L https://foundry.paradigm.xyz | bash安装脚本通常会提示将 Foundry 的可执行文件目录加入 PATH。按照终端提示重新加载 Shell 配置,或者关闭终端后重新打开。
然后安装工具链并检查版本:
# 下载并安装 Foundry 工具链
foundryup
# 检查核心工具是否已进入 PATH
forge --version
cast --version
anvil --version
chisel --version预期结果:foundryup 完成安装,后续四条命令均能输出版本信息。版本号、提交标识和构建日期随安装版本变化,不需要与其他机器完全一致。
创建 Forge 工程
在准备存放代码的目录中执行初始化命令。以下示例使用 contract-lab 作为项目名称,要求同名目标目录尚不存在。
# 创建包含示例合约、测试与脚本的工程
forge init contract-lab
cd contract-lab
# 查看当前工程使用的 Foundry 配置
forge config预期结果:forge init 成功创建工程,forge config 输出当前生效的配置。默认模板通常包含 Counter.sol 合约、对应测试文件、部署脚本和 forge-std 依赖。
默认初始化通常还会创建 Git 仓库,并将 forge-std 作为项目依赖安装。因此初始化阶段需要 Git 可用,首次下载依赖时需要访问网络。
如果工程目录已经存在并希望直接在其中初始化,可以进入空目录后执行 forge init。不要直接对包含重要代码的非空目录使用强制初始化选项,以免造成文件冲突。
识别工程目录与依赖关系
Forge 默认使用明确的目录约定,编译器会根据配置读取 Solidity 源文件,并通过导入路径解析测试依赖。
| 路径 | 主要职责 | 默认示例 |
|---|---|---|
src/ |
放置业务合约源码 | Counter.sol |
test/ |
放置 Solidity 测试合约 | Counter.t.sol |
script/ |
放置部署和交互脚本 | Counter.s.sol |
lib/ |
保存项目依赖 | forge-std/ |
foundry.toml |
配置项目目录、编译和测试选项 | [profile.default] |
out/ |
保存编译产物 | 编译时生成 |
cache/ |
保存增量编译缓存 | 编译时生成 |
下面的结构图展示各目录在编译和测试过程中的关系。

其中,forge-std 是 Foundry 常用的 Solidity 测试标准库,提供 Test 基类、断言方法和测试辅助功能。默认测试通常会从 forge-std/Test.sol 导入 Test,不需要手动复制标准库源码。
打开根目录的 foundry.toml,典型配置如下:
[profile.default]
src = "src"
out = "out"
libs = ["lib"]这是配置文件示例,表示源码目录为 src,编译输出目录为 out,依赖搜索目录包含 lib。部分模板还会包含其他设置,以实际生成内容为准。
执行以下命令查看 Forge 实际解析到的导入映射:
forge remappings预期结果:输出包含以 forge-std/ 为前缀、指向 lib/forge-std/src/ 的映射。实际路径表示可能因工具链和项目配置不同而变化。
编译合约并运行基础测试
初始化成功不代表工程一定能够编译。还需要检查 Solidity 编译器、源码导入以及测试运行器是否正常。
在 contract-lab 根目录执行:
# 编译工程中的 Solidity 合约
forge build
# 执行默认模板中的测试
forge test预期结果:
forge build成功完成编译,不出现 Solidity 编译错误。forge test显示测试执行结果,默认模板中的测试应通过。- 工程中生成或更新
out/与cache/目录。
不同 Foundry 版本的控制台日志、编译文件数量、Gas 数值以及默认测试数量可能不同,应以编译成功和测试全部通过为验收标准。
可以进一步使用详细模式观察测试信息:
# 输出更详细的测试执行结果
forge test -vv预期结果:终端显示测试名称和执行状态;测试通过时显示成功统计。此命令不会主动部署合约到真实区块链,也不需要配置钱包私钥。
为了确认测试依赖确实可用,可以查看 test/Counter.t.sol,检查它是否导入 forge-std/Test.sol,以及测试合约是否继承 Test。若导入成功并能执行断言,说明基础测试依赖已正确接入。
处理初始化与编译失败
初次搭建时,最常见的问题集中在命令路径、Git 依赖、Solidity 编译器下载和导入解析。
| 现象 | 可能原因 | 排查与处理 |
|---|---|---|
foundryup: command not found |
Shell 尚未加载 PATH | 重新打开终端,检查 Foundry 安装脚本给出的 PATH 配置提示 |
forge: command not found |
工具链未安装完成 | 重新执行 foundryup 并检查 forge --version |
| 初始化时依赖下载失败 | Git 或网络访问异常 | 检查 git --version、网络代理和 GitHub 连通性 |
Source ... not found |
依赖缺失或 remappings 错误 | 检查 lib/forge-std 并执行 forge remappings |
| 无法下载 Solidity 编译器 | 编译器尚未缓存且网络不可用 | 恢复网络后重新执行 forge build |
| 编译报 Solidity 版本不匹配 | pragma 与编译器配置冲突 |
检查源码版本约束和 foundry.toml 的 solc_version 设置 |
当 forge-std 目录确实缺失时,可在工程根目录安装依赖:
# 仅在依赖缺失时执行,避免重复安装
forge install foundry-rs/forge-std
# 重新检查导入映射并编译
forge remappings
forge build预期结果:依赖成功安装到项目依赖目录,映射能够解析 forge-std/,编译不再因缺少 Test.sol 而失败。安装依赖需要能够访问相应的 Git 仓库。
如果修改配置后出现异常,先运行 forge config 确认实际生效值,而不是直接删除整个项目。需要清除编译缓存时,可以使用 forge clean,它会清理构建产物和缓存,但不会删除 src/、test/ 中的源码。
验收可用于模糊测试的工程基线
最后执行一次完整检查,将结果作为后续开发和排错的参照:
# 确认编译、基础测试和依赖映射都正常
forge build
forge test
forge remappings预期结果:编译成功、基础测试全部通过,且输出能够识别 forge-std 的导入映射。
验收时同时确认以下项目:
src/Counter.sol存在且可编译。test/Counter.t.sol存在且其测试可以执行。script/包含初始化生成的脚本文件。lib/forge-std/包含标准库源码。foundry.toml能被 Forge 正确读取。out/中存在编译产物,且测试结果没有失败项。
这套基线说明合约编译、依赖解析和测试执行链路已经接通。后续加入带随机参数的模糊测试时,如果出现失败,就可以优先检查新增测试逻辑和合约行为,而不必重新怀疑整个工程是否初始化成功。