TypeScript Node.js项目Heroku部署失败求助：编译错误与配置问题排查

云上老周

2026-4-28

Hey there, let's work through your Heroku deployment issues with your TypeScript app—those compile errors are definitely frustrating, but we can tackle them one by one based on the logs you shared.

1. Fixing TypeScript Compilation Errors

Let's break down each key error from your Heroku build log and apply targeted fixes:

Error: Cannot find module 'path' or its corresponding type declarations + Cannot find name 'require'

These pop up because Heroku doesn't install devDependencies by default, and your @types/node (which provides type definitions for Node.js core tools like path and require) lives in devDependencies.

Fix:
Either:

Move @types/node from devDependencies to dependencies in your package.json, or
Tell Heroku to install devDependencies during build by setting an environment variable:
```
heroku config:set NPM_CONFIG_PRODUCTION=false
```
This ensures TypeScript and all type definition packages are available during the build process.

Error: Cannot find module 'express' declaration file

Same root cause as above—@types/express is in devDependencies. Use either of the fixes listed for the path/require error to resolve this.

Error: Cannot find name '__dirname'

__dirname is a CommonJS-specific variable. If your TypeScript config targets ES modules, it won't be available by default.

Fix:
Choose one of these options:

Add this code to the top of app.ts to manually define __dirname for ES modules:

import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

Or update your tsconfig.json to use CommonJS modules by adding:
```
"compilerOptions": {
  "module": "CommonJS"
}
```

Error: Property 'includes' does not exist on type 'string[]'

Your lib setting in tsconfig.json is set to es6, but Array.prototype.includes was added in ES2016.

Fix:
Update the lib array in tsconfig.json to include a newer ES version:

"lib": ["es2018", "dom.iterable", "dom"]

2. Clean Up Your Deployment Scripts

Your postinstall script uses risky commands like mv public dist/ and rm -rf src that can cause unexpected issues. Instead, we'll copy the public folder to dist during the build step (safer and more reliable).

Steps:

Install copyfiles as a dev dependency to simplify file copying:
```
npm install --save-dev copyfiles
```

Update your build and postinstall scripts in package.json:

"scripts": {
  "start": "node dist/server.js",
  "build": "tsc && copyfiles -u 1 public/**/* dist/",
  "postinstall": "npm run build",
  "start:dev": "nodemon server.ts -e ts,js,scss,hbs",
  "sass:dev": "node-sass -rw public/sass/ -o public/styles",
  "test": "echo \"Error: no test specified\" && exit 1",
  "deploy": "git add . && git commit -m Heroku && git push heroku master"
}

The -u 1 flag removes the top-level public folder from the path, so files land directly in dist/public.

Remove the rm -rf src line from postinstall—deleting source files on Heroku is unnecessary and risky.

3. Revised tsconfig.json

Here's an updated tsconfig.json incorporating all the fixes above:

{
  "compilerOptions": {
    "noImplicitAny": true,
    "preserveConstEnums": true,
    "sourceMap": true,
    "target": "ES2018",
    "module": "CommonJS",
    "moduleResolution": "node",
    "downlevelIteration": true,
    "lib": ["es2018", "dom.iterable", "dom"],
    "outDir": "dist",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "types": ["node"]
  }
}

4. Final Deployment Steps

After making these changes:

Commit your updates to Git:

git add .
git commit -m "Fix TypeScript deployment errors"

Push to Heroku:
```
git push heroku master
```

These changes should resolve the compilation errors and get your app deployed successfully. Once it's live, you can circle back to fixing any other issues with public files or other parts of your project.

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

TypeScript Node.js项目Heroku部署失败求助：编译错误与配置问题排查

1. Fixing TypeScript Compilation Errors #