本地正常运行的JS应用部署Heroku时出现模块找不到错误

问题根源 #

报错显示找不到./dist模块，调用栈指向mongoose依赖的mongodb包。本地运行正常但Heroku部署后崩溃，核心原因通常是依赖安装不完整或Heroku构建流程存在遗漏。

分步解决方案 #

1. 排查Heroku构建日志 #

Heroku部署时自动执行npm install，若依赖安装过程中有警告或失败，会导致模块缺失：

• 进入Heroku应用控制台，点击"More" > "View logs"
• 搜索npm install相关输出，确认是否存在安装错误

2. 清除Heroku缓存并重新部署 #

Heroku会缓存node_modules，缓存损坏可能导致依赖异常。执行以下命令：

heroku plugins:install heroku-builds
heroku builds:cache:purge -a calm-crag-33682
git commit --allow-empty -m "Purge Heroku cache"
git push heroku main

3. 修正package.json依赖配置 #

• 确保所有生产依赖都在dependencies字段下，不要放在devDependencies（Heroku默认不安装dev依赖，除非设置NPM_CONFIG_PRODUCTION=false）
• 锁定mongodb和mongoose的稳定版本，避免版本兼容问题，示例：

  "dependencies": {
    "mongodb": "^4.13.0",
    "mongoose": "^6.8.4"
  }
  

• 本地执行npm install后，提交package-lock.json到仓库，保证Heroku安装的依赖版本与本地完全一致

4. 验证MongoDB Atlas连接配置 #

• 在Heroku控制台"Settings" > "Config Vars"中添加MONGODB_URI，值为你的Atlas连接字符串
• 代码中通过process.env.MONGODB_URI获取连接地址，禁止硬编码

关于Heroku付费的说明 #

• 免费版应用会在30分钟无活动后休眠，唤醒有延迟，且每月有运行时长限制
• 若需要应用稳定在线、更低延迟、更多资源，或需要自定义域名、SSL等功能，付费Hobby计划是合理选择
• 当前崩溃问题与付费无关，先解决部署和依赖问题，再根据实际使用需求决定是否付费

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