Hardhat项目编译报ERR_DLOPEN_FAILED错误及npm空目录问题求助

问题背景 #

尝试创建新Hardhat项目，使用预生成的.sol文件和脚本，执行npx hardhat compile时触发以下错误：

\\?\C:\Users\myuser\Desktop\SolidityProjects\emptyhardhatfinal\node_modules\@nomicfoundation\solidity-analyzer-win32-x64-msvc\solidity-analyzer.win32-x64-msvc.node    at Object.Module._extensions..node (node:internal/modules/cjs/loader:1210:18)
    at Module.load (node:internal/modules/cjs/loader:1004:32)
    at Function.Module._load (node:internal/modules/cjs/loader:839:12)
    at Module.require (node:internal/modules/cjs/loader:1028:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (C:\Users\myuser\Desktop\SolidityProjects\emptyhardhatfinal\node_modules\@nomicfoundation\solidity-analyzer\index.js:69:29)    at Module._compile (node:internal/modules/cjs/loader:1126:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1180:10)
    at Module.load (node:internal/modules/cjs/loader:1004:32)
    at Function.Module._load (node:internal/modules/cjs/loader:839:12) {
  code: 'ERR_DLOPEN_FAILED'
}

操作步骤 #

• npm init -y
• npm i --dev hardhat
• npx hardhat 创建JavaScript项目
• npm i --dev @nomicfoundation/hardhat-toolbox
• 执行npx hardhat compile触发错误

环境信息 #

• Node.js版本：v16.17.0
• 用户环境变量：C:\Users\myuser\AppData\Roaming\npm（该文件夹为空）
• 系统环境变量：C:\Program Files\nodejs\
• 正常运行项目的电脑中，AppData\Roaming\npm目录存在node_modules文件夹

问题原因 #

1. 二进制依赖损坏/未完整安装：@nomicfoundation/solidity-analyzer的Windows平台二进制文件（.node）在安装过程中可能因网络或缓存问题损坏，导致Node.js无法加载该模块，抛出ERR_DLOPEN_FAILED错误。
2. 全局npm目录异常：用户的AppData\Roaming\npm为空，说明全局npm环境未正确初始化，可能影响依赖的解析和运行时加载逻辑。
3. Node.js版本兼容性：Node.js v16.17.0与最新版@nomicfoundation/hardhat-toolbox的部分二进制依赖存在兼容性差异，部分底层模块对Node.js版本有特定要求。

解决方法 #

方法1：清理缓存并重新安装项目依赖 #

• 删除项目根目录下的node_modules文件夹和package-lock.json文件
• 执行npm cache clean --force清理npm本地缓存
• 重新安装开发依赖：npm install --dev hardhat @nomicfoundation/hardhat-toolbox
• 再次执行编译命令：npx hardhat compile

方法2：修复全局npm目录 #

• 检查全局npm前缀路径：执行npm config get prefix，确认输出为C:\Users\myuser\AppData\Roaming\npm
• 若路径正确但目录为空，手动创建全局node_modules文件夹：mkdir C:\Users\myuser\AppData\Roaming\npm\node_modules
• 更新全局npm到稳定版：npm install -g npm

方法3：切换兼容的Node.js版本 #

• 使用Node版本管理器（如nvm）切换到Node.js v18.x或v20.x稳定版（Hardhat官方推荐版本）
• 卸载当前Node.js，重新安装官方发布的v18.x/v20.x稳定版
• 重新初始化项目并安装依赖，执行编译命令

方法4：临时禁用Solidity Analyzer #

• 在项目根目录的hardhat.config.js中添加配置，关闭solidity-analyzer：

module.exports = {
  solidity: "0.8.19", // 根据项目实际使用的Solidity版本调整
  settings: {
    analyzer: {
      enabled: false
    }
  }
};

• 保存配置后再次执行npx hardhat compile

内容的提问来源于stack exchange，提问作者Turgay ÇABALAK