Node.js: Error: Cannot find module

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

Node.js не нашёл модуль, указанный в require() или import. Для пакетов из npm поиск идёт в папках node_modules вверх по дереву каталогов, для относительных путей (./file) — по файловой системе. Поэтому причины делятся на две группы: не установлена зависимость или неверный путь/запуск. Сообщение содержит имя модуля и стек Require stack, который показывает файл, откуда вызов.

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

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

1. Прочитайте сообщениеСкопируйте полный текст ошибки Cannot find module '...' или ERR_MODULE_NOT_FOUND и посмотрите Require stack либо путь файла, где расположен import. Имя может обозначать пакет npm, локальный файл или встроенный модуль. Сначала проверьте опечатку: ./utils.js и utils.js означают разные способы импорта. Если в ошибке фигурирует один файл проекта, его не нужно ставить через npm. Зафиксируйте версию Node.js (node --version) и команду, которой запускали скрипт; для старой версии условия разрешения модулей могут отличаться.
2. Проверьте текущую папкуОткройте терминал редактора в корне проекта и проверьте его: в Windows PowerShell выполните Get-Location, в Linux/macOS — pwd. Выполните ls или dir и найдите package.json. Если файла нет, перейдите к корню через cd "реальный_путь". Выполните node --version и npm --version; проверьте поле engines и требования проекта. Если Node отсутствует в PATH либо версия не поддерживается, сначала восстановите окружение по руководству проекта, а не создавайте package.json там, где его не было.
3. Установите зависимостиЕсли не найден сторонний пакет, откройте package.json и проверьте разделы dependencies и devDependencies. При наличии действительного package-lock.json, созданного для этого проекта, в корне можно выполнить npm ci: команда удаляет и пересоздаёт node_modules на основе файла блокировки. Перед запуском сохраните несохранённые локальные изменения и убедитесь, что в node_modules нет вручную помещённых файлов. Для проекта без согласованного lock-файла используйте документированный способ установки (например, npm install) вместо безусловного удаления зависимостей.
4. Установите конкретный пакетЕсли нужного внешнего пакета нет в package.json, уточните его настоящее название и требуемую версию в документации проекта. В корне проекта выполните npm install express лишь если проект действительно использует express, либо замените имя официальным пакетом. Команда изменяет package.json и lock-файл; проверьте git diff до фиксации. Если ошибка относится к встроенному модулю Node, не устанавливайте одноимённый сторонний пакет без проверки: возможно, проект требует более новую версию Node.js.
5. Проверьте путьЕсли в проблемном require или import путь начинается с ./ или ../, откройте импортирующий файл в редакторе и найдите строку. Проверьте существование цели относительно этого файла, регистр букв на Linux, расширение и расположение сборочного вывода. В TypeScript не пытайтесь запускать .ts обычным Node без соответствующего инструмента; путь, существующий в исходниках, может отсутствовать в dist. Сохраните исправление, выполните проектную команду сборки и повторите запуск, проверив, что резолвится именно ожидаемый файл.
6. Проверьте расширение и тип модуляПосмотрите поле "type" в package.json и расширения .cjs/.mjs: режим ECMAScript-модулей и CommonJS отличается. Для относительного импорта в ESM Node обычно требует полный путь с расширением, например import helper from './helper.js'; require('./helper') относится к CommonJS. Не меняйте глобально "type" ради одной ошибки: это повлияет на все файлы проекта. Если ошибка связана с экспортами пакета, изучите его поле exports и поддерживаемые точки входа в официальной документации.
7. Переустановите node_modulesЕсли зависимости явно повреждены и проект поддерживает npm, сначала убедитесь, что lock-файл сохранён и актуален, затем выполните один согласованный способ восстановления: обычно npm ci. Не удаляйте package-lock.json и не очищайте весь кеш npm без подтверждения причины; при неудаче прочитайте сообщение об ошибке установки, включая несовместимые версии и права каталога. Проверка npm ls --depth=0 показывает проблемы верхнего уровня, но может сообщать об ожидаемых дополнительных зависимостях; сопоставьте вывод с манифестом.
8. Проверьте глобальные пакетыЕсли ошибку видите при вызове команды (webpack, vite, eslint), а не при require, проверьте наличие скрипта в package.json и выполните npm run имя_скрипта либо npm exec -- имя_утилиты согласно документации. Глобальная установка не нужна для обычного локального проекта; она может скрыть несовместимость версий. После исправления снова запустите первоначальную команду и проверьте тесты проекта. Если сбой остаётся, приложите текст ошибки, node --version, npm --version и список зависимостей без секретов.
9. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Диагностика версии и зависимостей в корне проекта.

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Диагностика версии и зависимостей в корне проекта. npm ls иногда возвращает ненулевой код при проблемах в дереве зависимостей.

   node --version

   npm --version

   npm ls --depth=0

   Вариант 2Пересоздаёт node_modules, поэтому предварительно проверьте, нет ли внутри несохранённых файлов; не удаляйте…

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Пересоздаёт node_modules, поэтому предварительно проверьте, нет ли внутри несохранённых файлов; не удаляйте package-lock.json.

   # В корне npm-проекта с СОГЛАСОВАННЫМ package-lock.json:

   npm ci

   Вариант 3Альтернатива для Windows.

   Windows · PowerShellКомандаКопировать всёВыделить

   Альтернатива для Windows. Это не третий обязательный шаг; используется вместо предыдущего блока.

   # PowerShell, та же операция только при наличии правильного lock-файла:

   npm ci

Если пакет установлен, но не находится, проверьте, что установка происходила в той же папке, откуда запускается скрипт; у монорепозиториев зависимости могут лежать в корне (workspaces). Ошибка в Docker часто означает, что node_modules не скопирован в образ или перекрыт томом. Для TypeScript проверьте, что собранные файлы находятся в dist/, а путь в package.json (main) указывает на существующий файл. Версию Node.js фиксируйте в .nvmrc, чтобы окружения совпадали. Документация — Node.js: модули.