AM
Веб-разработка 3 мин чтения

Как исправить ошибку Node.js MODULE_NOT_FOUND

Инструкция по устранению распространенной ошибки `MODULE_NOT_FOUND` в Node.js, которая возникает, когда Node.js не может найти запрошенный модуль.

Node.jsnpmMODULE_NOT_FOUNDзависимостиотладкаJavaScriptCI/CD

Симптомы

  • В консоли или логах появляется сообщение об ошибке `Error: Cannot find module 'имя-модуля'`.
  • Код ошибки `code: 'MODULE_NOT_FOUND'`.
  • Приложение Node.js не запускается или завершается сбойно.
  • Скрипты в CI/CD падают с ошибкой 'Cannot find module' на шаге, который должен использовать локальные файлы.

Возможные причины

  • Модуль не установлен: Самая частая причина, когда необходимый пакет не был установлен через npm или yarn.
  • Неправильный путь к модулю: Модуль существует, но Node.js не может его найти из-за некорректного относительного или абсолютного пути. Это часто встречается в CI/CD, когда скрипт пытается получить доступ к файлу до того, как репозиторий был клонирован или файлы стали доступны (например, до `actions/checkout`).
  • Поврежденная директория `node_modules`: Иногда файлы в `node_modules` могут быть повреждены, неполными или отсутствовать из-за проблем с установкой.
  • Отсутствие модуля в `package.json` или устаревшие зависимости: Модуль не указан как зависимость, или используемая версия пакета имеет внутренние проблемы с разрешением модулей (как было замечено в Artillery, SOURCE 2).
  • Проблемы с кэшем npm/yarn: Кэш может содержать устаревшие или поврежденные данные, мешающие корректной установке.
  • Несоответствие между CommonJS (require) и ES-модулями (import): В некоторых случаях, особенно при работе с TypeScript или смешанными модулями (.cjs/.mjs), могут возникать проблемы с разрешением.

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

1

Шаг 1: Проверьте установку модуля

Убедитесь, что все необходимые зависимости проекта установлены. Если ошибка указывает на конкретный модуль, попробуйте установить его вручную. Это самый распространенный сценарий.

Команда 
npm install
# Если ошибка указывает на конкретный модуль, например 'some-module':
npm install some-module
2

Шаг 2: Переустановка зависимостей и очистка кэша

Поврежденная или неполная директория `node_modules` часто является причиной этой ошибки. Удаление и повторная установка всех зависимостей, а также очистка кэша npm/yarn, может решить проблему, устраняя любые несоответствия или поврежденные файлы.

Команда 
rm -rf node_modules
npm cache clean --force
npm install
3

Шаг 3: Проверка путей к модулям и конфигурации CI/CD

Если ошибка возникает в среде CI/CD (например, GitHub Actions), убедитесь, что скрипты, требующие файлов проекта, выполняются *после* шага клонирования репозитория (`actions/checkout`). Как показано в SOURCE 3, запуск скрипта до того, как файлы проекта будут доступны, приведет к `MODULE_NOT_FOUND`. Также проверьте, что пути к модулям в вашем коде корректны, особенно при использовании относительных путей.

Команда 
# Пример для GitHub Actions:
# - uses: actions/checkout@v4  # Этот шаг должен быть первым
# - run: npm install
# - run: node scripts/my-script.js # Скрипт запускается после checkout и npm install
4

Шаг 4: Обновление устаревших зависимостей

Иногда ошибка `MODULE_NOT_FOUND` может быть вызвана внутренними проблемами в устаревших версиях зависимостей, которые были исправлены в более новых версиях. Обновление пакетов может помочь, как это было в случае с Artillery (SOURCE 2), где обновление решило проблему `MODULE_NOT_FOUND` для внутренних модулей.

Команда 
npm update
# Или для конкретного пакета:
npm install <имя-модуля>@latest
5

Шаг 5: Проверка `package.json` и переменной `NODE_PATH`

Убедитесь, что все необходимые модули перечислены в секциях `dependencies` или `devDependencies` файла `package.json`. Если модуль отсутствует, Node.js не сможет его найти. В редких случаях, если вы используете глобальные модули или нестандартные пути, проверьте переменную окружения `NODE_PATH`, хотя это не рекомендуется для большинства проектов.

Команда 
cat package.json
echo $NODE_PATH

Ошибка MODULE_NOT_FOUND является одной из наиболее распространенных проблем при работе с Node.js и npm. Она указывает на то, что среда выполнения Node.js не смогла найти запрошенный модуль по указанному пути. Это может произойти по нескольким причинам, от банального отсутствия установки пакета до более сложных проблем с путями или кэшем. Понимание корневой причины является ключом к быстрому устранению этой ошибки. В этой статье мы рассмотрим наиболее эффективные методы устранения этой проблемы, опираясь на распространенные сценарии и примеры из реальных проектов.

Проверка состояния пакетов

Выполните sudo apt —fix-broken install (Debian/Ubuntu) или sudo dnf distro-sync (Fedora) для исправления сломанных зависимостей. Проверьте повреждённые пакеты: sudo dpkg —audit (Debian) или sudo rpm -Va (RHEL). Это покажет, какие файлы изменены или отсутствуют.

Очистка кеша

Очистите кеш пакетов: sudo apt clean (Debian) или sudo dnf clean all (Fedora). Удалите неиспользуемые зависимости: sudo apt autoremove. Это освободит место и устранит конфликты версий. Если ошибка в репозитории, проверьте /etc/apt/sources.list на наличие неверных URL.

Переустановка пакета

Для переустановки повреждённого пакета: sudo apt install —reinstall имя-пакета. Если пакет зависит от других повреждённых, переустановите их все. Проверьте версию: apt show имя-пакета. Убедитесь, что версия совместима с вашейОС.

Исправление ключей GPG

Если ошибка связана с подписью пакета (NO_PUBKEY), обновите ключи: sudo apt-key adv —keyserver keyserver.ubuntu.com —recv-keys КЛЮЧ. Или: sudo gpg —keyserver keyserver.ubuntu.com —recv КЛЮЧ. Для Fedora: sudo rpm —import /etc/pki/rpm-gpg/RPM-GPG-KEY-*.

Проверка репозиториев

Убедитесь, что репозитории доступны и не дублируются: apt-cache policy (Debian) или dnf repolist (Fedora). Отключите ненужные репозитории: sudo add-apt-repository —remove ppa:имя. Для Fedora: sudo dnf config-manager —set-disabled репозиторий. Конфликтующие репозитории — частая причина ошибок.

Источники

  1. github.com — проверено 28.05.2026
  2. github.com — проверено 28.05.2026
  3. github.com — проверено 28.05.2026
  4. github.com — проверено 28.05.2026
  5. github.com — проверено 28.05.2026