如何解决npx hardhat compile执行异常及ESM项目配置问题

解决「执行npx hardhat compile弹出项目创建菜单」的问题 #

• 必须在项目根目录执行命令，不要进入contracts或其他子目录，Hardhat需要读取根目录下的配置文件才能识别项目。
• 确认根目录下存在hardhat.config.js（或后续修改的.cjs文件）、package.json、contracts文件夹这些初始化后的核心文件，若缺失则重新执行npx hardhat完成初始化。

解决「ESM项目与Hardhat配置文件后缀冲突」的问题 #

因为你在package.json中设置了"type": "module"，Node会把所有.js文件当作ESM模块，但Hardhat默认的配置文件是CommonJS格式，所以会报错。提供两种解决方案：

方案一：改用CommonJS配置文件（推荐，兼容性更好） #

• 直接把根目录下的hardhat.config.js重命名为hardhat.config.cjs
• 保持配置文件内的require写法不变，回到项目根目录执行npx hardhat compile即可

方案二：使用ESM格式配置文件 #

• 确保你的Hardhat版本≥2.12.0（可通过npx hardhat --version查看，版本过低则执行npm install hardhat@latest升级）
• 把hardhat.config.js中的require语句替换为import，比如：

  // 原CommonJS写法
  // const { ethers } = require("hardhat");
  
  // ESM写法
  import { ethers } from "hardhat";
  

• 若导入本地文件，需添加完整后缀（比如import "./utils.js"而不是import "./utils"）

额外排查步骤 #

• 在package.json的scripts中添加编译脚本：

  "scripts": {
    "compile": "hardhat compile"
  }
  

  之后执行npm run compile，避免npx的路径识别问题
• 执行npx hardhat clean清理编译缓存后，再重新编译
• 执行npm install确保所有Hardhat依赖都完整安装

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