Node.js LinuxWindowsmacOS

Node.js: ERR_MODULE_NOT_FOUND в ES-модулях

  • Обновлено
  • Чтение ≈ 3 минуты

Краткий ответ

В ESM нужно указывать расширение файла в import и корректный type в package.json. Проверьте путь и exports пакета.

В этой статье
  1. Что означает ошибка
  2. Причины и решения
  3. Пошаговое решение
  4. Относительные импорты
  5. Пакеты и exports
  6. Конфигурация

#Что означает ошибка

Сообщение
ERR_MODULE_NOT_FOUND

Error [ERR_MODULE_NOT_FOUND]: Cannot find module в ESM-проектах Node.js возникает, когда импорт не может быть разрешён строгими правилами ES-модулей. В отличие от CommonJS, ESM требует полного расширения файла и не подставляет index.js.

Ошибка часто появляется после перевода проекта на "type": "module".

Проверьте путь, расширение и поле exports пакета.

В ESM нужно указывать расширение файла в import и корректный type в package.json. Проверьте путь и exports пакета.

#Причины и решения

Возможная причинаКак узнатьЧто делать
Нет расширения.js.Ошибка.Добавьте.
Неверный путьФайл.Ошибка.Исправьте.
type: modulepackage.json.Ошибка.Настройте.
Нет пакетаnode_modules.Ошибка.npm install.

#Пошаговое решение

  1. Добавьте расширение .js в импортыВ терминале проекта выполните исходную команду запуска, например node app.mjs, и прочитайте полный текст ошибки ERR_MODULE_NOT_FOUND. Скопируйте путь из Cannot find module ... imported from ...; он показывает, что именно Node не смог разрешить. Сначала различите относительный импорт ./... и имя пакета react/другой зависимости. Не начинайте с переустановки всех зависимостей: отсутствие локального файла и отсутствие пакета решаются по-разному.
  2. Проверьте установку пакетаЕсли в ошибке указан относительный путь, откройте файл-источник и найдите строку import. В стандартном ESM Node для относительного файла укажите расширение: вместо ./utils используйте ./utils.js, а вместо ./lib — ./lib/index.js, если такой файл действительно есть. Учитывайте регистр имени (Utils.js не utils.js в Linux), наличие компиляции TypeScript в dist и относительность к импортирующему файлу. Снова запустите приложение и убедитесь, что ошибка исчезла; если Node теперь сообщает другой путь — исправляйте его отдельно.
  3. Проверьте поле exports пакетаЕсли не найден сторонний пакет, откройте терминал в папке с package.json, проверьте запись в dependencies/devDependencies и выполните npm ls имя-пакета заменив имя на то, что указано в ошибке. Если отсутствует, используйте штатную установку проекта — npm ci при наличии package-lock.json, иначе npm install согласно правилам проекта. Проверьте, что вы не запускаете код из другого каталога и пакет установлен именно в нужном рабочем пространстве. Не добавляйте зависимость глобально для локального импорта.
  4. Проверьте type в package.jsonЕсли Node пишет ERR_PACKAGE_PATH_NOT_EXPORTED вместо ERR_MODULE_NOT_FOUND, это отдельная ошибка: откройте node_modules/имя-пакета/package.json и изучите exports, затем используйте публичный путь, указанный в документации пакета. Попытки импортировать pkg/lib/private.js напрямую могут запрещаться самим пакетом, даже когда файл существует. Для ERR_MODULE_NOT_FOUND сначала устраните реальное отсутствие файла/пакета, а не меняйте type автоматически.
  5. Используйте import.meta.url вместо __dirnameСверьте в ближайшем package.json поле type и расширения .mjs, .js, .cjs, если после исправления пути возникла ошибка модулей. __dirname и require относятся к CommonJS и не доступны напрямую в обычном ESM; при необходимости используйте import.meta.url или createRequire по назначению. Для TypeScript с NodeNext проверьте, что выходная сборка и относительные импорты согласованы; затем повторите запуск и, если ошибка сохранилась, запишите полный путь и версию node -v.

#Относительные импорты

Укажите расширение: import { a } from "./utils.js" (даже если исходник TypeScript — пишите .js). Для каталогов указывайте ./dir/index.js явно. Проверьте регистр имён и существование файла. Если проект на TypeScript с "module": "NodeNext", расширения .js обязательны. Запустите исходную команду и прочитайте точный путь Cannot find module ... imported from ...; --trace-warnings не является основным средством диагностики ошибки разрешения модулей.

#Пакеты и exports

Для пакетов проверьте, что они установлены: npm ls имя. Если пакет использует поле exports, можно импортировать только заявленные подпути (import x from "pkg/feature"). Глубокие импорты pkg/lib/file.js блокируются. Для CommonJS-пакетов в ESM используйте import pkg from "pkg" и createRequire: import { createRequire } from "module"; const require = createRequire(import.meta.url);.

#Конфигурация

Проверьте "type": "module" в package.json и расширения файлов .mjs/.cjs. __dirname и require в ESM недоступны: используйте import.meta.url и fileURLToPath. Алиасы путей (@/) в чистом Node не работают — используйте imports в package.json ("#utils/*": "./src/utils/*.js") или сборщик. Для загрузчиков tsx/ts-node ESM: node --import tsx app.ts.

ТекстКоманда
Пример вспомогательных средств ESM; не является универсальным исправлением ERR_MODULE_NOT_FOUND.
import { createRequire } from "node:module";
import { fileURLToPath } from "node:url";
// Используется только при необходимости в настоящем ES-модуле
const require = createRequire(import.meta.url);
const moduleDir = fileURLToPath(new URL(".", import.meta.url));

Так эту ошибку тоже называют

Node.js: Error: listen EADDRINUSE :::3000 — причины и решение Остановите процесс, занявший порт, или смените порт. Программирование и базы данных Node.js LinuxWindowsmacOS Node.js: JavaScript heap out of memory — причины и решение Увеличьте --max-old-space-size и найдите утечку. Программирование и базы данных Node.js LinuxWindowsmacOS Node.js: Cannot use import statement outside a module — причины и решение Ошибка возникает при использовании import в CommonJS-файле. Укажите "type": "module" в package.json или переименуйте файл в .mjs. Программирование и базы данных Node.js LinuxWindowsmacOS Node.js: FATAL ERROR: JavaScript heap out of memory — причины и решение «FATAL ERROR: JavaScript heap out of memory» в Node.js возникает, когда процесс исчерпал лимит памяти V8. Увеличьте --max-old-space-size, найдите утечку, обрабатывайте д… Программирование и базы данных Node.js LinuxWindowsmacOS Node.js: The engine "node" is incompatible with this module — причины и решение Проект требует другую версию Node.js, чем установлена. Ниже — причины и порядок действий от простого к сложному. Программирование и базы данных Node.js WindowsLinux

Источники и обновления

Последнее обновление статьи: 1 ноября 2026. Версии программ и интерфейсы меняются — если шаги не совпадают с вашей версией, сверяйтесь с документацией производителя.