Как разработчики JavaScript и TypeScript, мы часто сталкиваемся с неожиданными ошибками при работе с различными модульными системами. Одной из распространенных проблем является ошибка «Невозможно использовать оператор импорта вне модуля». Обычно это возникает при работе с современными ES-модулями (ESM) или при работе с настройками, включающими упаковщики, такие как среды Webpack, Babel или Node.js. В этом блоге мы рассмотрим, что вызывает эту ошибку, почему она возникает, а также практические решения по ее устранению.

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

Ошибка «Невозможно использовать оператор импорта вне модуля» не требует пояснений: она возникает, когда JavaScript встречает оператор импорта вне допустимого модуля ES. В JavaScript модульные системы определяют, как разбивается код. в несколько файлов и то, как они взаимодействуют друг с другом. Модули ES (импорт/экспорт) и CommonJS (require/module.exports) являются двумя основными системами модулей.

Если JavaScript не распознает ваш код как ES-модуль, он выдает эту ошибку.

Что вызывает ошибку «Невозможно использовать оператор импорта вне модуля»?

Обычно это происходит, когда JavaScript/TypeScript встречает оператор импорта вне контекста модуля. Это означает, что файл, из которого вы пытаетесь импортировать, не распознается как модуль ES.

Вот еще несколько распространенных причин возникновения этой ошибки:

• Node.js использует CommonJS по умолчанию: по умолчанию Node.js использует модули CommonJS (CJS), а не модули ES. Это означает, что синтаксис импорта/экспорта не поддерживается изначально, если не указано иное.

• Неправильная конфигурация Babel/Webpack: при объединении вашего кода такие инструменты, как Babel или Webpack, могут быть не настроены для правильной обработки модулей ES, особенно если целевая среда не поддерживает их изначально.

• Отсутствует «тип»: «модуль» в package.json: если вы используете ES-модули в проекте Node.js, вам необходимо указать его явно, добавив «тип» : «модуль» в вашем package.json.

• Несоответствие расширения файла: иногда использование .js вместо .mjs для модулей ES или наоборот может привести к этой ошибке.

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

Вот несколько решений, позволяющих исправить ошибку «Невозможно использовать оператор импорта вне модуля»:

• Включить ES-модули в Node.js:

Наиболее распространенный случай — это работа с Node.js, который по умолчанию использует модули CommonJS. Чтобы включить модули ES, выполните следующие действия:

Метод 1. Измените package.json:

{
  "type": "module"
}

Добавляя «type»: «module» в ваш package.json, вы указываете Node.js обрабатывать все файлы .js как ES-модули.

Способ 2. Переименуйте файлы в .mjs:

Если вы не хотите изменять свой package.json, вы можете переименовать свои файлы в .mjs (например, index.mjs), чтобы явно указать, что они являются модулями ES.

• Обновить конфигурацию Babel/Webpack:

Если вы используете Babel или Webpack, убедитесь, что они настроены для правильной обработки модулей ES. Для Babel вы можете использовать плагин @babel/preset-modules. Для Webpack установите для модуля значение false в вашей конфигурации.

Для Babel: обновите файл .babelrc или Babel.config.json:

{
  "presets": ["@babel/preset-modules"]
}

Для Webpack: обновите файл webpack.config.js:

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      }
    ]
  }
};

• Проверьте путь импорта и синтаксис:

Убедитесь, что ваши пути импорта верны и вы используете правильный синтаксис. Например, относительные пути должны начинаться с ./ или ../.

Если вы импортируете модуль из node_modules, убедитесь, что пакет поддерживает модули ES. Если нет, вам может потребоваться использовать для этого сборщик, например Webpack.

• Двойная проверка расширений файлов:

Если вы используете модули ES, убедитесь, что расширения файлов соответствуют типу модуля. Используйте .mjs для модулей ES и .js для модулей CommonJS.

• .mjs: ES-модули
• .cjs: модули CommonJS

В чем разница между модулями ES и модулями CommonJS?

Итак, на ум приходит одна вещь: в чем разница между модулями ES и модулями CommonJS? И почему в JavaScript существуют две разные системы модулей?

ES-модули

Модули ES — это официальная система модулей JavaScript, представленная в ES6 (ES2015). Они используют ключевые слова импорта и экспорта для определения зависимостей между модулями. Модули ES доступны для статического анализа, что означает, что зависимости разрешаются во время компиляции, что упрощает оптимизацию кода.

ES-модули загружаются асинхронно, что позволяет повысить производительность и параллельную загрузку модулей. Они также поддерживают именованный экспорт, экспорт по умолчанию и циклические зависимости. Модули ES широко поддерживаются в современных браузерах и Node.js (с флагом «type»: «module»).

CommonJS-модули

CommonJS — это система модулей, которая использовалась в Node.js и других средах до появления модулей ES. Модули CommonJS используют функцию require для импорта модулей и модуль.exports или экспорт для экспорта значений. Модули CommonJS загружаются синхронно, что может привести к проблемам с производительностью.

Модули CommonJS не поддерживаются браузерами изначально, но их можно перенести в модули ES с помощью таких инструментов, как Babel или Webpack. Модули CommonJS по-прежнему широко используются в проектах Node.js, но модули ES становятся все более популярными из-за их лучшей производительности и возможности статического анализа.

Причина существования этих двух систем модулей связана с развитием JavaScript и необходимостью в более современной, стандартизированной системе модулей. Модули ES — это будущее модулей JavaScript, но модули CommonJS по-прежнему широко используются в существующих проектах и ​​средах.

Советы по отладке

Если вы попробовали все приведенные выше решения и по-прежнему сталкиваетесь с ошибкой, вот несколько дополнительных советов по отладке:

• Проверьте версию Node.js: убедитесь, что вы используете Node.js версии 12.x или выше, поскольку поддержка модулей ES была изначально введена в Node.js 12. Если вы в более старой версии модули ES не будут работать. Обновите свою версию, посетив веб-сайт Node.js.

• Проверьте поддержку браузера: если вы работаете в среде браузера, убедитесь, что ваш браузер поддерживает модули ES. Большинство современных браузеров поддерживают эту функцию, однако более старые версии могут этого не делать.

• Проверка на наличие опечаток: иногда простая опечатка в коде может вызвать эту ошибку. Дважды проверьте свой код на наличие орфографических ошибок или неправильного синтаксиса.

• Используйте npx tsc для TypeScript: если вы используете TypeScript и столкнулись с этой ошибкой, запустите npx tsc, чтобы скомпилировать код TypeScript в JavaScript, что может помочь обнаружить проблемы.

Заключение

Ошибка «Невозможно использовать оператор импорта вне модуля» — это распространенная проблема, с которой сталкиваются разработчики JavaScript/TypeScript при работе с ES-модулями. Поняв, почему возникает эта ошибка, и следуя пошаговым решениям, представленным в этом блоге, вы сможете быстро устранить ее и продолжить создание модульного, легко поддерживаемого кода.