在搭建ZK-EVM与Solidity开发环境的过程中，开发者经常会遭遇一些看似复杂、实则根源清晰的常见问题。本文聚焦于这些高频出现的配置与连接难点，逐条拆解并提供可落地的解决方案，帮助你快速扫清障碍，顺利完成环境搭建。
为什么直接使用 solc 安装会遇到“command not found”报错
这个问题并非你操作有误。从Solidity官方下载的二进制文件在Linux环境下默认不具备可执行权限，并且未注册到系统的$PATH环境变量中。因此，当你尝试执行./solc --version时，系统要么返回Permission denied，要么直接提示command not found，显得非常不友好。
正确的安装流程如下：
- 首先，前往Solidity的GitHub releases页面，下载名称中包含
solc-static-linux的二进制包（例如solc-static-linux-v0.8.26+commit.8b712ec9），避免误下载源码包。 - 下载完成后，赋予该文件执行权限：
chmod +x solc-static-linux-v0.8.26+commit.8b712ec9。 - 为了方便后续调用，可将文件重命名为
solc，然后创建软链接至系统路径：sudo ln -sf $(pwd)/solc /usr/local/bin/solc。 - 最后进行验证：运行
solc --version，若能正常输出版本信息而非“No such file”，即表示安装成功。
ZK-EVM 节点启动时卡在 Waiting for L1 RPC endpoint 无法继续
这是启动Scroll、Taiko等ZK-EVM本地开发节点时最常见的“瓶颈”。节点日志反复提示“等待L1 RPC”，问题根源通常不在网络，而是配置缺失——你尚未提供一个正确、可用的以太坊L1节点端点。
排查时请重点检查以下环节：
- 配置项核对：确保
l1-eth-rpc配置指向一个已完成同步的L1节点。若本地运行geth或erigon，务必确认启动了--http服务，并开放必要的API，例如--http.api=eth,net,web3。 - 公共RPC细节：若使用Infura等公共服务，URL格式必须完整，例如
https://mainnet.infura.io/v3/YOUR-PROJECT-ID，遗漏/v3/或Project ID将导致连接失败。 - 连通性测试：不要仅依赖节点日志。直接使用
curl命令手动测试RPC地址是否可用：curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' YOUR_RPC_URL。 - 特殊API需求：部分早期ZK-EVM实现（如Scroll的Alpha版本）要求L1节点额外支持
eth_getLogs等API。Geth默认未开启，需在启动参数中添加--http.api=eth,net,web3,debug。
hardhat-zksync 插件编译时出现 TypeError: Cannot read property 'config' of undefined
此错误是Hardhat与zkSync集成时的典型问题。表面上看是插件报错，实际根因在于项目配置——你虽然安装了hardhat-zksync插件，但Hardhat配置文件中缺少zksync配置对象。插件无法自动补全，一旦缺失便会直接罢工。
修复步骤非常明确：
- 版本兼容性：首先确认插件版本与Hardhat版本匹配。例如
hardhat-zksync@^0.8.0通常兼容Hardhat v2.14以下版本，而0.9.x可能不再兼容。 - 配置补充：打开
hardhat.config.ts，在module.exports的顶层对象中必须显式添加zksync: {}，即便暂时为空对象。这是插件生效的“入场券”。 - 本地节点连接：若使用
zksync-cli start-node启动本地节点，需在zksync对象内指定节点地址：zksync: { zksyncNodeUrl: "https://localhost:3050" }。 - 导入顺序：配置文件顶部导入插件时需注意顺序。通常先导入
@matterlabs/hardhat-zksync-solc，再导入@matterlabs/hardhat-zksync-deploy，顺序错误可能导致插件注册失败。
本地部署合约后 zkSync Explorer 无法查询到交易记录
这个问题令许多开发者感到困惑：明明在本地节点上部署成功，为什么到zkSync官方区块浏览器（如https://zksync2-testnet.zkscan.io）却查不到任何记录？
原因很简单且关键：官方浏览器仅索引和展示对应测试网或主网的数据。你在本地zksync-cli或era-test-node上运行的链，与公共网络完全是两条独立的链，浏览器自然不会也无力显示你的本地交易。这不是数据延迟，而是根本不在同一链路体系。
因此，调试本地合约应采用本地化方法：
- 命令行查询：使用
zksync-cli工具直接查询：zksync-cli get-transaction --hash 0x... --network https://localhost:3050。 - 编程接口：通过
ethers.js等库连接本地节点，调用provider.getTransactionReceipt()获取交易收据，无需依赖浏览器。 - 本地化浏览器：若确需图形界面，可尝试运行zkSync Era官方提供的本地区块浏览器（通常借助Docker Compose启动）。注意其后端也必须配置连接你自己的本地节点。
- 版本区分：最后提醒，zkSync v1（Legacy）与v2（Era）的浏览器地址、API格式完全不同。当前常用的
zksync2-testnet指代v2网络，而许多旧教程中的zksync.io/explorer已停止服务。
总而言之，将本地开发链与公共区块链浏览器视为两套独立系统，这一概念在zkSync生态中比在以太坊（Ganache + Etherscan）中更容易混淆，但也更需要厘清。
