执行yarn hardhat compile触发HH502错误，请求排查解决

问题场景 #

按照Hardhat官方教程创建新项目，执行yarn hardhat compile命令时触发HH502错误，提示无法下载编译器版本列表。

错误信息 #

Downloading compiler 0.8.9
(node:3732) ExperimentalWarning: stream/web is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
Error HH502: 无法下载编译器版本列表，请检查网络连接后重试。

HardhatError: HH502: 无法下载编译器版本列表，请检查网络连接后重试。 
    at /mnt/a/projects/Ethereum/hh-fcc/hardhat-simple-storage-2/node_modules/hardhat/src/internal/solidity/compiler/downloader.ts:149:17
    at processTicksAndRejections (node:internal/process/task_queues:96:5)
    at CompilerDownloader.downloadCompiler (/mnt/a/projects/Ethereum/hh-fcc/hardhat-simple-storage-2/node_modules/hardhat/src/internal/solidity/compiler/downloader.ts:142:5)
    at SimpleTaskDefinition.action (/mnt/a/projects/Ethereum/hh-fcc/hardhat-simple-storage-2/node_modules/hardhat/src/builtin-tasks/compile.ts:551:9)
    at Environment._runTaskDefinition (/mnt/a/projects/Ethereum/hh-fcc/hardhat-simple-storage-2/node_modules/hardhat/src/internal/core/runtime-environment.ts:308:14)
    at Environment.run (/mnt/a/projects/Ethereum/hh-fcc/hardhat-simple-storage-2/node_modules/hardhat/src/internal/core/runtime-environment.ts:156:14)
    at SimpleTaskDefinition.action (/mnt/a/projects/Ethereum/hh-fcc/hardhat-simple-storage-2/node_modules/hardhat/src/builtin-tasks/compile.ts:678:36)
    at Environment._runTaskDefinition (/mnt/a/projects/Ethereum/hh-fcc/hardhat-simple-storage-2/node_modules/hardhat/src/internal/core/runtime-environment.ts:308:14)
    at Environment.run (/mnt/a/projects/Ethereum/hh-fcc/hardhat-simple-storage-2/node_modules/hardhat/src/internal/core/runtime-environment.ts:156:14)
    at Environment._runTaskDefinition (/mnt/a/projects/Ethereum/hh-fcc/hardhat-simple-storage-2/node_modules/hardhat/src/internal/core/runtime-environment.ts:308:14)

    Caused by: Error: getaddrinfo EAI_AGAIN binaries.soliditylang.org
        at GetAddrInfoReqWrap.onlookup [as oncomplete] (node:dns:71:26)
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command

运行环境 #

Windows系统下的WSL，具体版本信息：

node v16.13.2
yarn v1.22.15
hardhat v2.11.2

WSL配置详情：

BUILD:    19042
BRANCH:   vb_release
RELEASE:  Ubuntu 20.04.3 LTS
KERNEL:   Linux 4.4.0-19041-Microsoft
UPTIME:   0d 3h 18m

项目配置文件 (hardhat.config.js) #

require("@nomicfoundation/hardhat-toolbox");

/** @type import('hardhat/config').HardhatUserConfig */
module.exports = {
  solidity: "0.8.9",
};

解决方案 #

1. 修复DNS解析问题 #

错误日志中getaddrinfo EAI_AGAIN binaries.soliditylang.org表明DNS无法解析Solidity编译器的下载域名，可通过以下步骤解决：

• 在WSL终端执行ping binaries.soliditylang.org，确认是否能正常解析和连通。
• 若无法解析，修改WSL的DNS配置：
  1. 编辑/etc/resolv.conf文件，添加nameserver 8.8.8.8（谷歌公共DNS）。
  2. 为防止WSL自动覆盖DNS配置，创建/etc/wsl.conf文件并添加以下内容：

     [network]
     generateResolvConf = false
     

  3. 重启WSL（Windows命令行执行wsl --shutdown后重新打开终端）。

2. 手动指定Solidity编译器 #

若网络问题无法快速解决，可手动下载编译器并配置Hardhat使用本地版本：

• 下载对应版本（0.8.9）的Solidity编译器（选择linux-x86_64版本适配WSL）。
• 修改hardhat.config.js，指定编译器路径：

  require("@nomicfoundation/hardhat-toolbox");
  
  module.exports = {
    solidity: {
      version: "0.8.9",
      settings: {
        optimizer: {
          enabled: true,
          runs: 200
        }
      },
      compilers: [
        {
          path: "/path/to/your/solc-0.8.9" // 替换为实际编译器路径
        }
      ]
    }
  };
  

• 再次执行yarn hardhat compile。

3. 升级WSL内核 #

当前使用的WSL内核版本（4.4.0-19041-Microsoft）较旧，升级到WSL2可解决多数网络兼容性问题：

• 在Windows设置中启用"适用于Linux的Windows子系统"和"虚拟机平台"功能。
• 执行wsl --set-version Ubuntu-20.04 2（替换为你的WSL发行版名称）。
• 下载并安装WSL2内核更新包，重启WSL后重试编译。

4. 检查网络权限 #

• 确认Windows防火墙未阻止WSL的网络请求，可临时关闭防火墙测试。
• 若使用代理，需确保WSL已配置正确的代理环境变量（如HTTP_PROXY、HTTPS_PROXY）。

内容的提问来源于stack exchange，提问作者Josal