Πώς να διορθώσετε το σφάλμα "ERR_MODULE_NOT_FOUND" στις εισαγωγές ESM του Node.js

ERR_MODULE_NOT_FOUNDσημαίνει ότι το Node.js έφτασε στον φορτωτή λειτουργικής μονάδας ECMAScript και δεν μπόρεσε να επιλύσει τη λειτουργική μονάδα που ζητήθηκε από ένα import, import(), ή το σημείο εισόδου του προγράμματος. Στην τρέχουσα τεκμηρίωση του Node.js, αυτό το σφάλμα ορίζεται συγκεκριμένα ως σφάλμα επίλυσης του φορτωτή ESM. Το ανάλογο σφάλμα CommonJS είναι MODULE_NOT_FOUND. Δείτε την επίσημη αναφορά σφάλματος Node.js .

Η ταχύτερη λύση είναι να προσδιορίσετε ποιο είδος προσδιοριστή απέτυχε πριν αλλάξετε οτιδήποτε. Μια σχετική εισαγωγή όπως το ./utils/logger.jsακολουθεί διαφορετικούς κανόνες από μια εισαγωγή πακέτου όπως το lodash. Το Node.js ESM επιλύεται επίσης διαφορετικά από το CommonJS: οι σχετικές εισαγωγές απαιτούν σαφείς επεκτάσεις αρχείων και τα ευρετήρια καταλόγων δεν μαντεύονται αυτόματα. Αυτές οι διαφορές εξηγούν πολλές αποτυχίες μετά τη μετάβαση από require()στο import.

Τι ακριβώς δεν καταφέρνει να βρει το Node.js;

Ξεκινήστε με την πρώτη γραμμή του σφάλματος, όχι ολόκληρη την ιχνηλάτηση στοίβας. Συνήθως σας ενημερώνει τόσο για τον μη επιλυμένο στόχο όσο και για το αρχείο που προσπάθησε να τον εισαγάγει. Ταξινομήστε τον αποτυχημένο προσδιοριστή σε μία από αυτές τις ομάδες:

• Σχετικό αρχείο: ./utils/logger.js ή ../config.js.
• Απόλυτο αρχείο ή URL αρχείου: μια απόλυτη διαδρομή ή file:URL.
• Άδειο πακέτο: lodash , express, ή @scope/pkg.
• Υποδιαδρομή πακέτου: some-package/feature.js .
• Ψευδώνυμο εισαγωγής πακέτου: ένας εσωτερικός προσδιοριστής που ξεκινά με #, ορίζεται έως package.json "imports".

Η επίσημη τεκμηρίωση των ενοτήτων Node.js ECMAScript διαχωρίζει τους σχετικούς, τους γυμνούς και τους απόλυτους προσδιοριστές, επειδή δεν επιλύονται με τον ίδιο τρόπο. Μόλις μάθετε ποια κατηγορία απέτυχε, αποφύγετε τυχαίες διορθώσεις, όπως διαγραφή node_modulesή αλλαγή, package.jsonμέχρι τα στοιχεία να υποδείξουν εκεί.

Περιλαμβάνει μια τοπική εισαγωγή ESM την πραγματική επέκταση αρχείου;

Για τους σχετικούς και απόλυτους προσδιοριστές ESM, το Node.js απαιτεί την επέκταση αρχείου. Δεν αναζητά .js, .mjs, ή .jsonμετά από μια αποτυχημένη σχετική εισαγωγή. Η τρέχουσα τεκμηρίωση του Node.js ονομάζει αυτόν τον κανόνα υποχρεωτικές επεκτάσεις αρχείων και αναφέρει επίσης ότι τα ευρετήρια καταλόγων πρέπει να καθορίζονται πλήρως.

Εάν το αρχείο στον δίσκο είναι src/utils/logger.js, αυτή είναι η ασφαλής μορφή ESM:

import { logger } from './utils/logger.js';

Δεν:

import { logger } from './utils/logger';

Αυτή είναι μια από τις πιο σημαντικές διαφορές από την ανάλυση CommonJS. Η επίσημη τεκμηρίωση των πακέτων Node.js εξηγεί ότι require()μπορείτε να δοκιμάσετε επεκτάσεις και φακέλους, ενώ το πρόγραμμα φόρτωσης ESM δεν εκτελεί αναζήτηση επεκτάσεων.

Εισάγετε έναν κατάλογο αντί για ένα πραγματικό αρχείο;

Ένα έργο CommonJS μπορεί να βασίστηκε σε μια εισαγωγή καταλόγου που τελικά φόρτωσε ένα αρχείο index.js. Μην υποθέσετε ότι ο φορτωτής ESM θα κάνει το ίδιο. Εάν η δομή σας είναι:

src/
  config/
    index.js
  app.js

προτιμώ:

import config from './config/index.js';

προκειμένου:

import config from './config';

Η επίσημη τεκμηρίωση του ESM αναφέρει ότι τα ευρετήρια καταλόγου όπως το ./startup/index.js. Εάν η προσθήκη της επέκτασης εξακολουθεί να αποτυγχάνει, συγκρίνετε κάθε τμήμα διαδρομής με το πραγματικό δέντρο καταλόγων.

Λειτουργεί όντως το έργο ως ESM;

Το Node.js υποστηρίζει τόσο τις ενότητες CommonJS όσο και τις ECMAScript. Για .jsαρχεία, ο πιο σαφής δείκτης σε επίπεδο πακέτου είναι:

{
  "type": "module"
}

Τα αρχεία που τελειώνουν σε .mjsαντιμετωπίζονται πάντα ως ενότητες ES, ενώ τα αρχεία που τελειώνουν σε .cjsαντιμετωπίζονται πάντα ως CommonJS. Οι τρέχουσες εκδόσεις του Node.js μπορούν επίσης να ανιχνεύσουν σύνταξη ESM σε ορισμένα ασαφή αρχεία, αλλά η τεκμηρίωση του Node.js συνιστά σαφείς δείκτες πακέτων επειδή είναι πιο σαφείς για το Node.js, τα εργαλεία και τη μελλοντική συντήρηση.

Διαβάστε τους επίσημους κανόνες πακέτου και τύπου ενότητας πριν από την αλλαγή "type". Η αλλαγή ενός πακέτου από CommonJS σε ESM μπορεί να επηρεάσει πολλά αρχεία ταυτόχρονα. Επίσης, να θυμάστε ότι η προσθήκη "type": "module"δεν εγκαθιστά μια ελλείπουσα εξάρτηση ούτε διορθώνει μια λανθασμένη διαδρομή. Καθορίζει μόνο τον τρόπο με τον οποίο .jsερμηνεύονται τα σχετικά αρχεία.

Είναι όντως εγκατεστημένο σε αυτό το έργο το πακέτο που λείπει;

Εάν το σφάλμα ονομάσει ένα κενό πακέτο όπως το lodash, ελέγξτε το δέντρο εξαρτήσεων αντί να υποθέσετε ότι ένα καθολικά εγκατεστημένο πακέτο ή ένας άλλος χώρος εργασίας το καθιστά διαθέσιμο.

npm ls lodash

Η τρέχουσα τεκμηρίωση npm για το npm ls αναφέρει ότι η εντολή παραθέτει τις εγκατεστημένες εκδόσεις πακέτων και μπορεί να αναφέρει εξαρτήσεις που λείπουν ή είναι μη έγκυρες. Εάν το πακέτο είναι μια άμεση εξάρτηση χρόνου εκτέλεσης και δεν είναι εγκατεστημένο, εγκαταστήστε το στο σωστό έργο:

npm install lodash

Η επίσημη τεκμηρίωση εγκατάστασης του npm εξηγεί ότι μια κανονική εγκατάσταση έργου τοποθετεί εξαρτήσεις στο τοπικό node_modulesδέντρο και, από προεπιλογή, αποθηκεύει ρητά εγκατεστημένα πακέτα σε dependencies.

Σε ένα monorepo, εκτελέστε τον έλεγχο στον χώρο εργασίας που κατέχει το αρχείο εισαγωγής. Ένα πακέτο που εγκαθίσταται αλλού στο αποθετήριο δεν σημαίνει αυτόματα ότι το τρέχον πακέτο έχει μια έγκυρη δηλωμένη εξάρτηση.

Είναι σωστό το όνομα του πακέτου, αλλά λάθος η υποδιαδρομή;

Ένα πακέτο μπορεί να υπάρχει και να απορρίπτει μια βαθιά εισαγωγή. Τα σύγχρονα πακέτα μπορούν να ορίσουν έναν "exports"χάρτη στο package.json. Όταν υπάρχει αυτό το πεδίο, το Node.js επιτρέπει μόνο τα δημόσια σημεία εισόδου που δηλώνονται εκεί. Η επίσημη τεκμηρίωση του σημείου εισόδου πακέτου Node.js αναφέρει "exports"ότι έχει προτεραιότητα "main"σε σχέση με τις υποστηριζόμενες εκδόσεις Node.js και ενσωματώνει μη καταχωρημένες υποδιαδρομές.

Ας υποθέσουμε ότι μια εξάρτηση τεκμηριώνει αυτήν τη δημόσια εισαγωγή:

import { parse } from 'example-package/parser';

Μην το αντικαθιστάτε με μια πιθανολογούμενη εσωτερική διαδρομή όπως:

import { parse } from 'example-package/dist/internal/parser.js';

Μια αποκλεισμένη "exports"υποδιαδρομή συχνά παράγει ERR_PACKAGE_PATH_NOT_EXPORTEDαντί για ERR_MODULE_NOT_FOUND. Αυτή η αλλαγή στον κωδικό σφάλματος είναι χρήσιμη απόδειξη: σημαίνει ότι το Node.js βρήκε το πακέτο, αλλά η ζητούμενη διαδρομή δεν αποτελεί μέρος της δημόσιας διεπαφής του. Χρησιμοποιήστε την τεκμηριωμένη διαδρομή εισαγωγής του πακέτου αντί να παρακάμψετε την ενθυλάκωση.

Θα μπορούσε η διαδρομή να διαφέρει μόνο κατά την ορθογραφία ή την πεζά-κεφαλαία;

Ελέγξτε τον πραγματικό χαρακτήρα του δέντρου αρχείων για χαρακτήρες. Οι εισαγωγές που φαίνεται να λειτουργούν σε ένα σύστημα αρχείων ανάπτυξης που δεν κάνει διάκριση πεζών-κεφαλαίων ενδέχεται να αποτύχουν μετά την ανάπτυξη σε ένα σύστημα αρχείων που κάνει διάκριση πεζών-κεφαλαίων.

Για παράδειγμα, αν το πραγματικό αρχείο είναι:

src/utils/Logger.js

έπειτα μια εισαγωγή:

import logger from './utils/logger.js';

δεν είναι φορητό, επειδή Logger.jsτα και logger.jsμπορούν να έχουν διαφορετικά ονόματα αρχείων.

Επίσης, επαληθεύστε ότι η εισαγωγή είναι σχετική με την ενότητα εισαγωγής και όχι με τον τρέχοντα κατάλογο του κελύφους. Οι σχετικοί προσδιοριστές ESM επιλύονται σε σχέση με τη διεύθυνση URL της ενότητας του αρχείου εισαγωγής.

Πώς μπορείτε να δείτε τι θα έλυνε το Node.js;

Σε μια ενότητα ES, import.meta.resolve()μπορεί να βοηθήσει στην επιθεώρηση της ανάλυσης:

console.log(import.meta.resolve('./utils/logger.js'));
console.log(import.meta.resolve('lodash'));

Η επίσημη αναφορά ESM του Node.js περιγράφεται import.meta.resolve(specifier)ως μια συνάρτηση ανάλυσης σχετική με τη λειτουργική μονάδα που επιστρέφει μια απόλυτη συμβολοσειρά URL και τιμά την ανάλυση πακέτων και τις επιτρεπόμενες εξαγωγές.

Υπάρχει μια σημαντική προειδοποίηση για την τρέχουσα έκδοση: για έναν σχετικό file:στόχο, import.meta.resolve()μπορεί να επιστρέψει τη διεύθυνση URL ακόμα και όταν το αντίστοιχο τοπικό αρχείο δεν υπάρχει. Χρησιμοποιήστε το για να απαντήσετε στην ερώτηση "Σε ποιον στόχο επιλύει ο κόμβος αυτόν τον προσδιοριστή;" και, στη συνέχεια, επαληθεύστε ότι το αρχείο που προκύπτει υπάρχει όντως. Για ελλείποντα πακέτα ή μη έγκυρες αντιστοιχίσεις πακέτων, η ίδια η επίλυση μπορεί να αποκαλύψει την αποτυχία νωρίτερα.

Πρέπει να διαγράψετε το node_modules και το lockfile;

Όχι ως πρώτη απάντηση. Μια επέκταση που λείπει, μια λανθασμένη τοπική διαδρομή ή μια μη υποστηριζόμενη υποδιαδρομή πακέτου δεν θα επιδιορθωθεί με την επανεγκατάσταση εξαρτήσεων.

Εάν npm lsαναφέρει ένα ασυνεπές δέντρο, το έργο έχει ένα committed package-lock.json, και θέλετε μια αναπαραγώγιμη καθαρή εγκατάσταση, χρησιμοποιήστε:

npm ci

Η τρέχουσα τεκμηρίωση του npm ci αναφέρει ότι npm ciαπαιτεί ένα υπάρχον αρχείο κλειδώματος, καταργεί node_modulesαυτόματα τον υπάρχοντα κατάλογο, εγκαθιστά το κλειδωμένο δέντρο και δεν επανεγγράφει package.jsonτο αρχείο κλειδώματος. Εάν package.jsonτα στοιχεία και το αρχείο κλειδώματος διαφωνούν, τερματίζεται αντί να ενημερώνεται σιωπηλά το κλείδωμα.

Αποφύγετε τη διαγραφή package-lock.jsonαπλώς και μόνο για να εξαφανίσετε το σφάλμα. Αυτό μπορεί να προκαλέσει την επίλυση ενός νέου γραφήματος εξάρτησης και να μετατρέψει ένα σφάλμα επίλυσης λειτουργικής μονάδας σε αλλαγή έκδοσης εξάρτησης.

Ποια είναι η ταχύτερη σειρά αντιμετώπισης προβλημάτων;

Τι πρέπει να αποφεύγετε να αλλάζετε στα τυφλά;

• Μην προσθέτετε "type": "module"μόνο και μόνο επειδή μια εισαγωγή απέτυχε. Επιβεβαιώστε πρώτα το σύστημα ενοτήτων που προορίζεται για το έργο.
• Μην καταργείτε τις επεκτάσεις αρχείων για να μιμηθείτε παραδείγματα CommonJS. Το Node.js ESM απαιτεί σαφείς επεκτάσεις για σχετικούς και απόλυτους προσδιοριστές αρχείων.
• Μην εισάγετε σε βάθος ιδιωτικά αρχεία από μια εξάρτηση όταν ο "exports"χάρτης της παρέχει ένα υποστηριζόμενο δημόσιο σημείο εισόδου.
• Μην υποθέτετε ότι μια επιτυχημένη εγκατάσταση καθολικού npm καθιστά μια εξάρτηση διαθέσιμη σε μια τοπική εφαρμογή.
• Μην διαγράφετε ένα αρχείο κλειδώματος ως βήμα ρουτίνας καθαρισμού της προσωρινής μνήμης.
• Μην υποθέτετε ότι ο κατάλογος εργασίας ελέγχει τις σχετικές εισαγωγές ESM. Η ενότητα εισαγωγής είναι η βάση.

Πώς ξέρετε ότι η επιδιόρθωση έχει ολοκληρωθεί;

Εκτελέστε ξανά το ίδιο σημείο εισόδου που απέτυχε αρχικά και επιβεβαιώστε ότι η ενότητα επιλύεται χωρίς να αντικαταστήσει το σφάλμα με ένα άλλο πρόβλημα επίλυσης. Στη συνέχεια, εκτελέστε τις κανονικές δοκιμές ή την εντολή εκκίνησης του έργου, ώστε να γνωρίζετε ότι η διόρθωση λειτουργεί πέρα ​​από μια μεμονωμένη πρόταση εισαγωγής.

Εάν η εφαρμογή φτάσει τώρα σε διαφορετικό σφάλμα, όπως ERR_PACKAGE_PATH_NOT_EXPORTED, ERR_UNKNOWN_FILE_EXTENSION, ή σε σφάλμα ονόματος εξαγωγής, μην το αντιμετωπίσετε ως το ίδιο πρόβλημα. Αυτό σημαίνει ότι η επίλυση της ενότητας έχει προχωρήσει περαιτέρω και το Node.js αναφέρει πλέον μια πιο συγκεκριμένη ασυμβατότητα.

Συμπέρασμα

Για το Node.js ESM, ERR_MODULE_NOT_FOUNDσυνήθως επιλύεται με την ανίχνευση του ακριβούς προσδιοριστή αντί για την επανεγκατάσταση όλων των στοιχείων. Τα τοπικά αρχεία χρειάζονται σαφείς επεκτάσεις και σαφείς δείκτες καταλόγου. Τα γυμνά πακέτα πρέπει να εγκατασταθούν στο σωστό δέντρο εξαρτήσεων. Οι υποδιαδρομές πακέτων πρέπει να σέβονται το "exports". Ο έλεγχος package.jsonπρέπει να ταιριάζει με το προβλεπόμενο σύστημα λειτουργικών μονάδων και τα ονόματα αρχείων πρέπει να ταιριάζουν ακριβώς με το σύστημα αρχείων.

Μόλις προσεγγίσετε το σφάλμα με αυτήν τη σειρά — τύπος προσδιοριστή, πραγματική διαδρομή, κανόνες ESM, δέντρο εξαρτήσεων, εξαγωγές πακέτων και, στη συνέχεια, καθαρή εγκατάσταση — συνήθως μπορείτε να εντοπίσετε γρήγορα την αιτία χωρίς να εισαγάγετε άσχετες αλλαγές.