# Moccasin 的本地测试为何连了远端：核对 pyevm 与配置优先级

整理：链小知（AI 辅助）
资料核对日期：2026-10-12
引用地址：https://lianxiaozhi.com/tools/guides/moccasin-pyevm-config-local-test
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

沿着脚本、CLI 和配置文件逐级排查，并识别 fork 与 manifest_named 的外部读取/部署边界。

## 使用工具
- [Moccasin](https://lianxiaozhi.com/tools/moccasin) · [官方入口](https://cyfrin.github.io/moccasin/)

## 前置条件
- 准备 Moccasin/Vyper 工程副本和锁定依赖，使用无需生产账户的 Counter 类本地测试；依赖/编译器已准备。
- 官方 README 仍标 beta，文档更新时间不一；先对照已安装 mox test --help。测试代码要确认没有主动远端请求、fork 或真实部署。

## 1. 定位最终生效的网络设置

读取 moccasin.toml 和 pyproject.toml，以及测试/fixture 中对网络的设置。官方优先级是 Script > CLI > moccasin.toml > pyproject.toml > defaults；只改低优先级文件可能完全不生效。记录每个覆盖点，不打印账户、密码或完整带认证的 RPC URL。

核对结果：能指出最终设置来自哪一层；同名参数的覆盖关系明确。
依据：[Moccasin：配置优先级](https://cyfrin.github.io/moccasin/core_concepts/moccasin_toml.html)

## 2. 区分 pyevm、本地 fork 与真实网络

pyevm 是 titanoboa 提供的本地模拟网络，状态通常持续当前运行生命周期；远端 network 配置会直接接到对应 RPC，--fork 虽本地执行仍读远端数据。named contract 文档中的 Ethereum/Arbitrum 示例是配置例子，不能自动变成隔离环境。

核对结果：计划运行的是 pyevm；没有远端 URL/fork 或脚本主动切换。
依据：[Moccasin：pyevm 本地网络生命周期](https://cyfrin.github.io/moccasin/core_concepts/networks/pyevm.html)
依据：[Moccasin：manifest_named 的读取与部署边界](https://cyfrin.github.io/moccasin/core_concepts/named_contracts/manifest_named.html)

## 3. 检查看似读取的合约加载函数

逐个检查 fixture/辅助函数中的 manifest_named 或 get_or_deploy_named_contract。官方示例在合约缺失时会调用 deployer_script；函数名不能证明只是读取。确认本地 Mock 的部署目标和 ABI，不把 mainnet 地址塞进 pyevm 后期待自动读取真实资产。

核对结果：缺失合约分支的部署脚本与目标明确，所有合约状态来自本地测试。
依据：[Moccasin：manifest_named 的读取与部署边界](https://cyfrin.github.io/moccasin/core_concepts/named_contracts/manifest_named.html)
依据：[Moccasin：官方 README](https://raw.githubusercontent.com/Cyfrin/moccasin/main/README.md)

## 4. 只选已隔离的测试文件

在依赖已准备且代码检查完成后，可用 mox test tests/test_counter.py --network pyevm --no-install -x 运行实际文件路径。--no-install 仅阻止自动装依赖，-x 在首次失败退出；两个选项都不会阻止测试代码自己访问网络。脚本层设置仍可能覆盖 CLI，所以运行前的代码检查是必要条件。

核对结果：命令指定文件与 pyevm，帮助参数兼容；未把 no-install 解释成断网。
依据：[Moccasin：test 命令参数](https://cyfrin.github.io/moccasin/cli_reference/test.html)
依据：[Moccasin：配置优先级](https://cyfrin.github.io/moccasin/core_concepts/moccasin_toml.html)

## 5. 按失败阶段记录复现条件

编译/导入失败先核对 Vyper、Python 与依赖；断言失败保留初始值和期望值，不将它解释成主网合约行为。若日志出现远端 RPC 或账户加载，回到优先级和 fixture 分支检查。pyevm 重启后的状态不是上次真实部署的持久记录，结果需连同版本和测试文件保存。

核对结果：有版本、命令、环境、失败阶段与断言；无外部访问时才将结果称为已隔离的本地测试。
依据：[Moccasin：官方 README](https://raw.githubusercontent.com/Cyfrin/moccasin/main/README.md)
依据：[Moccasin：pyevm 本地网络生命周期](https://cyfrin.github.io/moccasin/core_concepts/networks/pyevm.html)
依据：[Moccasin：test 命令参数](https://cyfrin.github.io/moccasin/cli_reference/test.html)
依据：[Moccasin：配置优先级](https://cyfrin.github.io/moccasin/core_concepts/moccasin_toml.html)

## 常见错误
- CLI --network pyevm 的优先级低于脚本主动设置；参数本身不能保证隔离。
- fork 会读远端 RPC，--no-install 只约束依赖安装。
- manifest_named 可能部署 Mock，真实网络的同名调用也不能按纯读取理解。

## 完成检查
- 能够追溯配置来源、测试文件和辅助函数的网络行为。
- 本篇只经过官方文档核对；没有实际执行 Moccasin 隔离测试或广播部署。

## 相关知识

## 官方依据
- [Moccasin：配置优先级](https://cyfrin.github.io/moccasin/core_concepts/moccasin_toml.html)
- [Moccasin：pyevm 本地网络生命周期](https://cyfrin.github.io/moccasin/core_concepts/networks/pyevm.html)
- [Moccasin：manifest_named 的读取与部署边界](https://cyfrin.github.io/moccasin/core_concepts/named_contracts/manifest_named.html)
- [Moccasin：官方 README](https://raw.githubusercontent.com/Cyfrin/moccasin/main/README.md)
- [Moccasin：test 命令参数](https://cyfrin.github.io/moccasin/cli_reference/test.html)