Hey Leonardo, sorry to hear you're stuck with your Node API crashing on Heroku after working perfectly locally—let's break down the key differences between your local setup and Heroku's environment, plus how to leverage those heroku logs --tail outputs to debug the crash.

These are the most common areas where local and Heroku setups diverge, leading to crashes:

1. Environment Variables #

• Locally, you might use a .env file or manually set variables, but Heroku doesn't read .env files by default. All required variables (like database connection strings, API keys) need to be set via heroku config:set KEY=VALUE or the Heroku Dashboard's environment variables panel.
• Critical note: Heroku automatically assigns a PORT variable for your app to use. If your code hardcodes a port (like 3000) instead of using process.env.PORT, Heroku will refuse to start your app—this is one of the top causes of crashes.

2. Node.js & Package Manager Versions #

• Heroku defaults to a specific Node.js version unless you explicitly define it in your package.json with the engines field. Mismatched versions (e.g., you use Node 20 locally but Heroku uses Node 16) can cause compatibility errors. Add this to your package.json to lock versions:

  "engines": {
    "node": "20.x",
    "npm": "10.x"
  }
  

• Heroku runs npm install --production by default, meaning any packages in devDependencies won't be installed. If your app accidentally relies on a dev package (like a build tool you forgot to move to dependencies), it'll throw a "module not found" error.

3. File System & Git Sync #

• Heroku's file system is temporary and read-only (except for the /tmp directory). If your app tries to write to other directories (like saving uploads to a local uploads folder) or relies on files you didn't commit to Git (because they're in .gitignore), it'll fail.
• Double-check your .gitignore—if it excludes critical files/folders (like a dist build directory or config files), Heroku won't have access to them, leading to startup crashes.

4. Build & Startup Scripts #

• If you run manual build commands locally (like npm run build to compile TypeScript or bundle assets), Heroku won't do this automatically unless you define a build or heroku-postbuild script in package.json. For example:

  "scripts": {
    "start": "node dist/server.js",
    "build": "tsc",
    "heroku-postbuild": "npm run build"
  }
  

• Heroku uses either your package.json's start script or a Procfile to launch your app. If your start script points to the wrong entry file (e.g., node server.js but your built file is in dist/server.js), the app will crash immediately.

5. Process Management #

• Locally, you might run your app directly with node server.js, but Heroku manages processes differently. If your app exits immediately (e.g., unhandled error on startup), Heroku will mark it as crashed. It also automatically restarts crashed processes, but repeated failures will put it in a crash loop.

Your heroku logs --tail output will tell you exactly what's breaking—look for these common error messages:

• Error: listen EADDRINUSE :::XXXX: You're hardcoding a port instead of using process.env.PORT.
• Cannot find module 'XXX': Either the package is in devDependencies (so Heroku didn't install it) or the file wasn't committed to Git.
• ENOENT: no such file or directory: Missing file (check .gitignore and make sure you committed all necessary assets/builds).
• Connection refused: Your app can't reach an external service (like a database)—verify your environment variables have the correct connection string, and ensure the service allows Heroku's IPs to connect.

1. Verify your package.json's start script points to the correct entry file.
2. Run heroku config to confirm all required environment variables are set (no missing database URLs, API keys, etc.).
3. Add the engines field to match your local Node/npm versions.
4. Check your .gitignore to make sure it's not excluding critical files like dist or build.

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