Heroku部署Node.js项目卡在安装node modules问题求助

问题概述 #

首次通过GitHub导入Node.js项目到Heroku，配置Node.js buildpack和环境变量后执行部署，过程卡在安装node modules环节。已尝试删除本地node_modules、package-lock.json后重新推送，甚至删除应用重新部署，问题仍未解决。

相关信息 #

构建日志 #

-----> Building on the Heroku-24 stack
-----> Using buildpack: heroku/nodejs
-----> Node.js app detected
       
-----> Creating runtime environment
       
       NPM_CONFIG_LOGLEVEL=error
       NODE_VERBOSE=false
       NODE_ENV=development
       NODE_MODULES_CACHE=true
       
-----> Installing binaries
       engines.node (package.json):   20.15.0
       engines.npm (package.json):    10.9.0
       
       Resolving node version 20.15.0...
       Downloading and installing node 20.15.0...
       Bootstrapping npm 10.9.0 (replacing 10.7.0)...
       npm 10.9.0 installed
       
-----> Installing dependencies
       Installing node modules

package.json #

{
  "name": "xyz-crm-business-ai",
  "version": "1.0.0",
  "description": "Business AI Training Backend",
  "main": "server.js",
  "scripts": {
    "start": "node server.js",
    "build": "echo 'No build required'",
    "heroku-postbuild": "NPM_CONFIG_PRODUCTION=false npm install"
  },
  "dependencies": {
    "@supabase/supabase-js": "^2.39.0",
    "cors": "^2.8.5",
    "dotenv": "^16.3.1",
    "express": "^4.18.2",
    "morgan": "^1.10.0",
    "multer": "1.4.5-lts.1",
    "openai": "^4.20.1",
    "puppeteer": "^21.5.2"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

环境变量配置 #

SUPABASE_URL=*************
SUPABASE_KEY=*************
CLERK_SECRET_KEY=*************
DEV_FRONTEND_URL=http://localhost:5173
FRONTEND_URL=*************


# Server Configuration
PORT=3000
NODE_ENV=development
# File Upload Configuration
MAX_FILE_SIZE=10485760 # 10MB in bytes
MAX_FILES=10

# Chrome configuration
CHROME_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome  # For Mac
# CHROME_PATH=C:\Program Files\Google\Chrome\Application\chrome.exe  # For Windows
# CHROME_PATH=/usr/bin/google-chrome  # For Linux
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true  # Optional: Use system Chrome
CHROME_BIN=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

排查与解决方案 #

1. 提升日志级别，定位具体错误 #

当前日志级别为error，无法看到安装过程中的详细报错信息。需修改环境变量，将日志级别改为verbose：

• 在Heroku控制台的「设置」-「配置变量」中添加NPM_CONFIG_LOGLEVEL=verbose
• 或通过命令行执行：

  heroku config:set NPM_CONFIG_LOGLEVEL=verbose
  

重新部署后，查看完整构建日志，即可找到卡住的具体原因。

2. 修复Puppeteer的Chrome配置问题 #

项目依赖puppeteer，但环境变量中存在两个关键问题：

• PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true会跳过puppeteer自带的Chromium下载，但Heroku-24栈默认未安装Chrome
• CHROME_PATH和CHROME_BIN配置的是Mac本地路径，在Heroku的Linux服务器上完全无效

解决方案二选一：

• 移除PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true，让puppeteer自动下载适配Heroku的Chromium版本
• 添加Heroku Chrome buildpack，配置正确的服务器Chrome路径：
  1. 在Heroku控制台添加buildpack（需放在Node.js buildpack之前）
  2. 修改环境变量中的CHROME_BIN为/usr/bin/google-chrome，保留PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true

3. 优化heroku-postbuild脚本 #

当前heroku-postbuild脚本会强制在生产环境下重新安装所有依赖（包括devDependencies），可能引发重复安装或依赖冲突。

• 如果不需要部署devDependencies，直接删除heroku-postbuild字段
• 如果确实需要安装devDependencies，可修改脚本为：

  "heroku-postbuild": "npm install --only=dev && npm install --only=prod"
  

4. 检查Node.js与npm版本兼容性 #

虽然指定了node@20.15.0和npm@10.9.0，但部分依赖可能对新版本存在兼容性问题。可尝试降级到LTS版本（如Node.js 18.x）：

• 修改package.json中的engines字段：

  "engines": {
    "node": "18.x",
    "npm": "9.x"
  }
  

重新推送后部署，验证是否解决问题。

5. 临时禁用Node Modules缓存 #

Heroku默认开启依赖缓存，若缓存的依赖损坏可能导致安装卡住。临时禁用缓存后重新部署：

heroku config:set NODE_MODULES_CACHE=false

部署成功后，可再执行heroku config:unset NODE_MODULES_CACHE恢复默认设置。

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