So beheben Sie den Fehler „Modul kann nicht gefunden werden“ in Node.js und TypeScript

Der FehlerFehler: Modul ‘x’kann nicht gefunden werden (oderModul ‘x’ oder seine entsprechenden Typdeklarationenkann in TypeScript nicht gefunden werden) kommt sehr häufig vor. Es gibt mehrere unterschiedliche Ursachen – hier erfahren Sie, wie Sie die einzelnen Ursachen diagnostizieren und beheben können.

Ursache 1: Paket nicht installiert

# The most common cause — you forgot to install it
npm install express

# Reinstall everything if node_modules is corrupted
rm -rf node_modules package-lock.json
npm install

# Verify it's actually in package.json
npm list express

Ursache 2: Falscher Importpfad (relative Importe)

// 🐛 Wrong path
import { helper } from './utils/helper';  // but file is at ./lib/helper

// ✅ Fix: correct the relative path
import { helper } from './lib/helper';

// Common mistakes:
// - Missing ./ for local files: import x from 'utils' looks in node_modules
// - Wrong case: ./Helper vs ./helper (case-sensitive on Linux!)
// - Missing file extension in ESM (see Cause 5)

Ursache 3: Fehlende Typdeklarationen (TypeScript)

# Error: Cannot find module 'lodash' or its corresponding type declarations

# The package works but has no bundled types. Install @types:
npm install --save-dev @types/lodash

# For packages that will never have types, declare them:
# create src/types/untyped-module.d.ts
declare module 'some-untyped-package';

Ursache 4: tsconfig-Pfadaliase nicht konfiguriert

// You use import { x } from '@/utils' but it's not configured

// tsconfig.json — add path mapping
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

// For runtime (Node), you also need tsconfig-paths or a bundler:
// npm install -D tsconfig-paths
// node -r tsconfig-paths/register dist/index.js
// Or use tsx which handles this automatically

Ursache 5: ESM vs. CommonJS-Erweiterungsprobleme

// In ESM ("type": "module" in package.json), you MUST include .js extension
// even when importing .ts files:

// 🐛 Fails in ESM
import { helper } from './utils/helper';

// ✅ Correct in ESM
import { helper } from './utils/helper.js';  // yes, .js even for .ts source

// package.json
{
  "type": "module"
}

// tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"  // or "nodenext"
  }
}

Ursache 6: Modul installiert, aber nicht erstellt (Monorepo/Workspace)

# In a monorepo, the dependency package hasn't been built yet
# Cannot find module '@myorg/shared'

# Build the dependency first
npm run build --workspace=@myorg/shared

# Or build all packages (Turborepo/Nx)
turbo build
npx nx run-many --target=build

Diagnose-Checkliste

1. Ist es installiert? Führen Sienpm list <module>
2. aus Ist der Pfad korrekt? Überprüfen Sie die Groß-/Kleinschreibung und den relativen Pfad
3. Braucht es @types? Versuchen Sie es mitnpm i -D @types/<module>
4. ESM-Problem? Fügen Sie.jshinzu Erweiterungen, wenn"type": "module"
5. Pfad-Alias? Überprüfen Sie tsconfigpaths und Laufzeit-Resolver
6. Starten Sie den TS-Serverneu in Ihrem Editor (VS-Code: Cmd+Shift+P, dann „TS Server neu starten“)

Modulauflösung des Knotens – Funktionsweise

// import 'foo' (no ./) → Node looks in:
//   1. Core modules (fs, path, http)
//   2. node_modules in current dir
//   3. node_modules in parent dirs, up to root

// import './foo' (with ./) → resolves relative to current file
//   Looks for: ./foo.js, ./foo.json, ./foo/index.js, etc.

// Understanding this explains most "cannot find module" errors:
// - No ./ means Node searches node_modules (fails if it's a local file)
// - ./ means relative path (fails if the path is wrong)

Häufig gestellte Fragen

F: Warum funktioniert es lokal, schlägt aber auf dem Server/CI fehl?
A: Normalerweise wird die Groß-/Kleinschreibung beachtet – bei macOS/Windows wird die Groß-/Kleinschreibung nicht beachtet, bei Linux jedoch nicht. ./Helper funktioniert lokal, schlägt jedoch unter Linux fehl, wenn die Datei./helperist . Passen Sie immer die genaue Groß-/Kleinschreibung an.

F: Ich habe das Paket installiert, erhalte aber immer noch die Fehlermeldung. Warum?
A: Starten Sie den TypeScript-Server Ihres Editors oder den Entwicklungsserver neu. Überprüfen Sie außerdem, ob sich das Paket independenciesbefindet , nicht einfach lokal installiert ohne zu speichern. Löschen Sie „node_modules“ und installieren Sie es erneut, wenn Sie unsicher sind.

F: Was ist der Unterschied zwischen dem Modulfehler und dem Typdeklarationsfehler?
A: „Modul nicht gefunden“ allein = das JS-Modul wurde nicht gefunden. „…oder die entsprechenden Typdeklarationen“ = das Modul existiert, aber TypeScript kann keine Typen finden. Der zweite benötigt@types/x oder ein.d.ts Erklärung.

F: Wie behebe ich das in einem Docker-Build?
A: Stellen Sie sicher, dassnpm install Läuft innerhalb des Containers (kopieren Sie nicht die Knotenmodule des Hosts). Kopieren Sie zuerst package.json, installieren Sie es und kopieren Sie dann die Quelle – dies verbessert auch das Docker-Layer-Caching.

F: Sollte ich „moduleResolution“ verwenden: „node“ oder „bundler“?
A: Im Jahr 2026 verwenden Sie"bundler" für Projekte, die mit Vite/esbuild/webpack erstellt wurden (keine Erweiterung erforderlich), oder"nodenext" für reines Node ESM (Erweiterungen erforderlich). Vermeiden Sie das Erbe"node" für neue Projekte.

Fazit

„Modul kann nicht gefunden werden“ liegt fast immer an einem der folgenden Gründe: Das Paket ist nicht installiert, der Importpfad ist falsch (Groß-/Kleinschreibung prüfen!), fehlendes@types, ESM-Erweiterungsanforderungen oder nicht konfigurierte Pfadaliase. Gehen Sie die Diagnose-Checkliste von oben nach unten durch –npm list, überprüfen Sie den Pfad, suchen Sie nach@types, und starten Sie Ihren TS-Server neu. Neunzig Prozent der Fälle lösen sich in den ersten drei Schritten.