Heroku/Vercel部署时hardhat依赖未识别报Cannot find module错误

核心诱因 #

本地运行正常、线上部署报模块找不到，本质是线上生产环境的依赖解析逻辑和本地开发环境不一致，常见触发原因有三个：

• 依赖分类错误：安装Hardhat时默认将其放到了devDependencies分类下，Heroku、Vercel等平台默认生产环境部署时只会安装dependencies下的依赖，会直接跳过开发依赖，导致线上环境找不到Hardhat包
• 依赖全局安装问题：本地环境全局安装了Hardhat，项目本地node_modules中并没有安装Hardhat依赖，本地运行时可以从全局路径解析到包，但线上部署环境不会预装全局Hardhat，直接解析失败
• 构建缓存/版本不兼容：平台侧构建缓存异常导致依赖漏装，或者平台默认使用的Node.js版本和本地开发版本差距过大，Hardhat依赖安装失败

解决方案 #

按优先级依次排查处理：

1. 修正依赖分类
   在项目根目录执行命令，将Hardhat及代码中引入的所有Hardhat相关插件（比如@nomicfoundation/hardhat-toolbox、@nomiclabs/hardhat-ethers等）从开发依赖移到生产依赖：

   npm install hardhat @nomicfoundation/hardhat-toolbox --save
   

   不要遗漏代码中require()引入的所有Hardhat生态包，所有运行时需要用到的包都必须放在dependencies节点下。
2. 本地模拟生产环境验证
   删掉本地项目的node_modules文件夹和锁文件，执行生产环境安装+启动命令复现问题：

   rm -rf node_modules package-lock.json
   npm install --production
   npm start
   

   如果本地执行上述命令也报同样的找不到模块错误，继续补全缺失的依赖，直到本地生产模式启动完全正常，再推送代码到部署平台。
3. 平台侧配置调整
   • Heroku环境：临时快速验证可在平台配置变量中添加NPM_CONFIG_PRODUCTION=false，强制安装所有依赖（不推荐长期使用，会增大部署包体积）；同时在package.json的engines字段指定和本地一致的Node版本，避免版本兼容问题：

     "engines": {
       "node": "18.x"
     }
     

   • Vercel环境：部署前先清理平台构建缓存再重新触发部署；如果不想调整依赖分类，可以在项目根目录新建vercel.json，指定安装命令包含开发依赖：

     {
       "installCommand": "npm install --include=dev"
     }
     

4. 规避全局依赖问题
   不要依赖全局安装的Hardhat包，所有项目用到的依赖必须在项目本地执行安装命令写入package.json，确保部署时可以被平台自动安装。

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