Node.js: Cannot use import statement outside a module

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

SyntaxError: Cannot use import statement outside a module и ERR_REQUIRE_ESM возникают, когда Node.js запускает файл с import/export как CommonJS (или наоборот). Это несоответствие систем модулей.

Решение зависит от того, что вам удобнее: перейти на ESM или оставить CommonJS.

Ошибка возникает при использовании import в CommonJS-файле. Укажите "type": "module" в package.json или переименуйте файл в .mjs.

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

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

1. Определите тип модулейОткройте каталог проекта в VS Code либо другом редакторе и найдите входной файл из текста ошибки (app.js, index.js и т. п.). Затем откройте ближайший к нему package.json и проверьте поле type. Расширение .mjs всегда указывает на ES-модуль, .cjs — на CommonJS; файл .js зависит от type и в современных версиях Node возможен дополнительный анализ синтаксиса. Запустите node -v в терминале проекта: поведение и совместимость библиотек зависят от версии. Не изменяйте type всего проекта без оценки остальных файлов.
2. Добавьте type moduleЕсли проект целиком рассчитан на ES-модули, добавьте в корневой для этих файлов package.json поле "type": "module" или переименуйте один отдельный файл в .mjs. Перед изменением сохраните копию package.json и проверьте скрипты запуска, тесты и конфигурационные файлы. Успешное переключение означает, что Node разбирает import/export; однако require, module.exports и __dirname в этом контексте больше не будут доступны — исправляйте их по необходимости. Для проектов с множеством CommonJS-зависимостей удобнее ограничиться .mjs.
3. Уберите require и __dirnameЕсли остаётесь в CommonJS, используйте синтаксис const fs = require("node:fs") и module.exports = ... только в своих совместимых файлах; не делайте массовую автоматическую замену import на require. Пакеты только для ESM могут не загружаться через require в конкретной версии Node; для них используйте поддерживаемый динамический import() или мигрируйте соответствующий модуль. Проверка: запустите свою точку входа node app.cjs (замените имя на реальное) и посмотрите, исчезла ли именно исходная ошибка.
4. Добавьте расширения в импортыДля нативного ESM при относительном импорте укажите явный путь с расширением: import { foo } from "./foo.js", а для index — ./dir/index.js. Проверьте, что файл действительно существует в скомпилированном результате, а регистр совпадает (Linux чувствителен к регистру). В ESM нельзя просто вызвать require() или использовать __dirname; если нужен каталог текущего модуля, примените fileURLToPath(new URL(".", import.meta.url)) из node:url. Эти изменения относятся к настоящему ESM, не ко всем приложениям Node.js.
5. Проверьте tsconfigДля TypeScript сначала проверьте tsconfig.json, наличие сборки и настройки проекта; "module": "NodeNext" вместе с "moduleResolution": "NodeNext" — вариант, но он должен соответствовать package.json и фактическому способу запуска. Если ошибка происходит в Jest, ts-node или сборщике, ищите именно конфигурацию их загрузчика: изменение type само по себе может сломать тесты. Выполните тестовый запуск исходной команды и сравните с предыдущим стеком; при новой ошибке откатите последнее изменение и согласуйте один способ модулей для проекта.

#Перейти на ESM

В package.json добавьте "type": "module" либо переименуйте файл в .mjs. Тогда import fs from "fs" работает, а require и __dirname недоступны: используйте import { fileURLToPath } from "url"; const __dirname = path.dirname(fileURLToPath(import.meta.url));. В импортах локальных файлов указывайте расширение: ./utils.js.

#Оставить CommonJS

Замените import x from "y" на const x = require("y"), а export default на module.exports =. Если пакет — ESM-only (node-fetch 3, chalk 5), установите прежнюю версию npm i node-fetch@2 либо подключайте динамически: const fetch = (...a) => import("node-fetch").then(m => m.default(...a));.

#Инструменты

В TypeScript выставьте "module": "NodeNext" или "commonjs" в tsconfig.json; для Jest настройте трансформацию и поддержку ESM по документации используемой версии. Запуск ts-node для ESM: node --loader ts-node/esm. Проверьте версию Node (node -v): стабильная поддержка ESM с 14, Поддержка require() для ESM зависит от конкретного выпуска Node и ограничений модуля; не считайте её универсальной.

#Как проверить результат

Создайте файл test.mjs с содержимым import os from "os"; console.log(os.platform()); и запустите node test.mjs: если вывод появился, ESM работает. Для CommonJS проверьте node -e "console.log(require('os').platform())". Если ошибка осталась в Jest, проверьте jest.config.js и параметры transformIgnorePatterns для ESM-пакетов из node_modules.