Как исправить ERR_REQUIRE_ESM при подключении ESM-пакета в CommonJS

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

В проекте с require() после обновления зависимости появляется ERR_REQUIRE_ESM: пакет предоставляет ES-модуль, который данная версия Node.js не может загрузить синхронным require(). На современных версиях Node.js некоторые синхронные ESM уже поддерживаются через require(); поэтому сначала нужны версия среды, полный стек и проверка конкретного пакета. Инструкция касается загрузки ESM из CommonJS, а не отсутствующего пакета.

#Как отличить возможные причины

#Пошаговая диагностика и устранение

1. Убедитесь, что ошибка относится к загрузке ES-модуляКогда приложение не стартует, откройте папку проекта в редакторе VS Code (Файл → Открыть папку) и встроенный терминал (Терминал → Создать терминал). Запустите обычную команду старта, например node index.cjs; скопируйте из журнала именно ERR_REQUIRE_ESM, путь проблемного пакета и строку require(...). Если ошибка ERR_MODULE_NOT_FOUND, используйте диагностику отсутствующего файла: это другая ситуация.
2. Узнайте версию Node.js и менеджера пакетовВ терминале проекта выполните node --version и npm --version. Запишите версии и сравните с требованиями пакета в его документации и полем engines в package.json. В Node.js 22 и новее поведение require(esm) отличается от прежних выпусков: не считайте каждый импорт ESM автоматически несовместимым. Если команда node не найдена, сначала установите поддерживаемую версию Node.js официальным способом.
3. Определите, где находится CommonJS и где ESMНайдите строку const lib = require("имя-пакета") поиском по проекту (Ctrl+Shift+F). Проверьте расширение текущего файла: .cjs — CommonJS; .mjs — ESM; .js зависит от ближайшего package.json и синтаксиса. В node_modules не редактируйте исходники пакета: правки исчезнут при установке.
4. Сохраните изменяемый файл перед опытомПеред заменой кода скопируйте index.cjs под отдельным именем либо сохраните текущие изменения в Git. В редакторе откройте файл-источник ошибки. Не добавляйте в package.json "type":"module" только ради одной строки: это меняет режим всех .js в области пакета и может сломать другие require().
5. Замените require на динамический import() в CommonJSЕсли пакет экспортирует функцию по умолчанию, создайте асинхронную функцию и внутри неё выполните const { default: fn } = await import("имя-пакета"); затем вызовите fn(). Если библиотека предоставляет именованные экспорты, используйте соответствующие имена по документации. Ниже дан автономный пример с собственным ESM-файлом, без скачивания пакета.
6. Обработайте ошибку асинхронной загрузкиВызовите асинхронную функцию с .catch(err => { console.error(err); process.exitCode = 1; }). Теперь отказ импорта выводится в журнал, а процесс получает код ошибки, вместо молчаливого зависания. Если ошибка осталась — проверьте путь и имя экспорта; не подменяйте её случайным объектом из require().
7. Проверьте работу в той же среде, где проявилась ошибкаВ терминале выполните node index.cjs. В локальном примере ожидается Привет из ESM. Для настоящей зависимости повторите команду запуска приложения и проверьте реальное действие, ради которого подключена библиотека. В Docker/CI выполните проверку и там: локальный Node может быть другой версии.
8. Выберите долгосрочный вариант и способ откатаЕсли проект целиком ESM, планово переведите импорты на import и проверьте все пути и экспортируемые значения. Если обновление пакета несовместимо и исправление затронет много файлов, согласуйте использование предыдущей поддерживаемой версии; не фиксируйте старую небезопасную версию без оценки рисков. Для отката восстановите сохранённый файл и версию зависимости из package-lock.json.
9. Откройте терминал в каталоге проекта

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

   Откройте терминал в каталоге проекта. Команды не требуют прав администратора; последняя запускает собственный скрипт. Если файл назван иначе, используйте его точное имя.

   node --version

   npm --version

   node index.cjs

#Минимальный пример и проверка на тестовом проекте

export default function greet() { return "Привет из ESM"; }

async function main() {
  const { default: greet } = await import("./greet.mjs");
  console.log(greet());
}
main().catch(err => { console.error(err); process.exitCode = 1; });

#Проверка результата и действия при неуспехе

В тестовой папке node index.cjs печатает «Привет из ESM» и завершает работу с кодом 0. В проекте должна исчезнуть именно ERR_REQUIRE_ESM, а импортируемая функция должна работать; если возникла ERR_REQUIRE_ASYNC_MODULE, используйте import(), а не синхронный require. При новой ошибке сохраните версию Node.js, полный стек и exports пакета.