Предупреждение MISSING_GLOBAL_NAME

Предупреждение Rollup MISSING_GLOBAL_NAME появляется в момент формирования бандла в форматах, где внешние зависимости должны быть представлены через глобальные переменные среды выполнения (чаще всего UMD или IIFE). Оно означает отсутствие имени глобальной переменной для одного из модулей, помеченных как external.

В Rollup внешние зависимости могут быть исключены из сборки с помощью настройки external. В таком случае библиотека не встраивается в итоговый бандл, а предполагается, что она уже доступна в окружении выполнения.

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

  • UMD
  • IIFE

В этих форматах импорт:

import React from 'react';

превращается не в локальный модуль, а в обращение к глобальной переменной:

const React = window.React;

или:

const React = React;

в зависимости от окружения.

Если Rollup не знает, как называется глобальная переменная, он генерирует предупреждение:

MISSING_GLOBAL_NAME

Условия появления предупреждения

Предупреждение возникает при сочетании следующих факторов:

  • модуль указан как external
  • используется формат вывода iife или umd
  • отсутствует сопоставление в output.globals

Типичная конфигурация, вызывающая проблему:

export default {
  input: 'src/index.js',
  external: ['react'],
  output: {
    file: 'bundle.js',
    format: 'umd'
  }
};

В этом случае Rollup не знает, чему соответствует react в глобальной области.

Причина на уровне генерации бандла

При сборке UMD/IIFE Rollup строит карту зависимостей:

  1. Входной модуль анализируется
  2. Внешние импорты исключаются
  3. Для каждого external модуля требуется глобальный идентификатор
  4. Генерируется код, который обращается к этим глобальным именам

Если шаг 3 не выполнен, генератор кода не может безопасно скомпилировать обращение к зависимости, поскольку не существует универсального имени переменной.

Пример ошибки на практике

Исходный код:

import _ from 'lodash';

export function chunkArray(arr, size) {
  return _.chunk(arr, size);
}

Конфигурация Rollup:

export default {
  input: 'src/index.js',
  external: ['lodash'],
  output: {
    file: 'dist/bundle.umd.js',
    format: 'umd',
    name: 'MyLib'
  }
};

При сборке появляется предупреждение:

(!) MISSING_GLOBAL_NAME
Use output.globals to specify browser global variable names corresponding to external modules

Как Rollup ожидает решение

Rollup требует явного маппинга:

output: {
  globals: {
    lodash: '_'
  }
}

После этого генерируется код:

var _ = window._;

или UMD-обертка:

(factory(window._));

Настройка output.globals

output.globals — ключевой механизм устранения предупреждения.

Формат:

output: {
  globals: {
    [moduleName]: globalVariableName
  }
}

Пример:

export default {
  input: 'src/index.js',
  external: ['react', 'react-dom'],
  output: {
    file: 'dist/bundle.js',
    format: 'umd',
    name: 'MyLibrary',
    globals: {
      react: 'React',
      'react-dom': 'ReactDOM'
    }
  }
};

Частые библиотеки и их глобальные имена

На практике большинство популярных библиотек имеют устоявшиеся глобальные идентификаторы:

Модуль Глобальная переменная
react React
react-dom ReactDOM
lodash _
jquery jQuery или $
axios axios

Несовпадение регистра или имени приводит к ошибкам выполнения даже при отсутствии предупреждений.

Типичные сценарии возникновения

1. Подключение CDN-версий библиотек

Если React подключается через CDN:

<script src="https://unpkg.com/react/umd/react.production.min.js"></script>

то Rollup должен знать, что react соответствует React.

2. Разделение библиотек на peerDependencies

При разработке UI-библиотек часто используется:

"peerDependencies": {
  "react": "^18.0.0"
}

и external:

external: ['react']

Без globals UMD-сборка становится неполной.

3. Несовпадение имени пакета и глобальной переменной

Некоторые пакеты имеют сложные имена:

  • @scope/package
  • @babel/runtime

Для них требуется точное указание:

globals: {
  '@babel/runtime': 'BabelRuntime'
}

Как диагностировать проблему

Основные признаки:

  • предупреждение MISSING_GLOBAL_NAME
  • сборка UMD/IIFE проходит, но поведение нестабильно
  • в браузере возникает ReferenceError: X is not defined

Полезно проверить:

  • список external
  • формат output
  • наличие globals
  • совпадение имен с CDN

Глубокая причина в архитектуре Rollup

Rollup строго разделяет:

  • модульную систему (ESM/CJS)
  • глобальную среду выполнения (browser globals)

При ESM проблем нет — импорт резолвится на уровне бандлера.

При UMD/IIFE требуется мост между мирами:

external module name -> global variable name

Если мост не определён, генерация кода становится неоднозначной, поэтому Rollup выбирает безопасную стратегию — предупреждение вместо автоматического предположения.

Поведение при отсутствии globals

Если output.globals не задан:

  • Rollup продолжает сборку
  • external модуль остаётся без корректной ссылки
  • в коде появляется неопределённая переменная
  • результат зависит от runtime

Пример потенциально сломанного кода:

(function (global, factory) {
  factory(global.react);
})(this, function (React) {});

Если global.react отсутствует, библиотека падает при запуске.

Связь с форматами сборки

Проблема строго связана с форматами:

  • esm — не требует globals
  • cjs — не требует globals
  • umd — требует globals
  • iife — требует globals

Поэтому часто конфигурации разделяют:

output: [
  {
    file: 'dist/index.esm.js',
    format: 'esm'
  },
  {
    file: 'dist/index.cjs.js',
    format: 'cjs'
  },
  {
    file: 'dist/index.umd.js',
    format: 'umd',
    name: 'MyLib',
    globals: {
      react: 'React'
    }
  }
];

Частые ошибки конфигурации

1. Пропущенный модуль в globals

external: ['react', 'react-dom'],
globals: {
  react: 'React'
}

react-dom не указан → появляется предупреждение.

2. Несоответствие регистра

globals: {
  React: 'React'
}

Должно быть react, а не React.

3. Путаница с именами scoped-пакетов

external: ['@scope/utils'],
globals: {
  '@scope/utils': 'Utils'
}

Любое отклонение от точного имени ломает маппинг.

Подход к исправлению

Рабочая последовательность:

  1. Проверяется external
  2. Определяется формат сборки
  3. Составляется список внешних зависимостей
  4. Каждой зависимости назначается глобальное имя
  5. Добавляется output.globals

Практический шаблон конфигурации

const external = ['react', 'react-dom'];

export default {
  input: 'src/index.js',
  external,
  output: {
    file: 'dist/bundle.umd.js',
    format: 'umd',
    name: 'LibraryName',
    globals: {
      react: 'React',
      'react-dom': 'ReactDOM'
    }
  }
};

Роль предупреждения в экосистеме Rollup

MISSING_GLOBAL_NAME выполняет функцию раннего обнаружения архитектурной несогласованности между:

  • модульной системой сборки
  • глобальным runtime окружением браузера

Он предотвращает ситуации, когда библиотека собирается успешно, но падает при первом запуске в production окружении.

Поведение при игнорировании предупреждения

Игнорирование приводит к:

  • runtime ошибкам в браузере
  • нарушению UMD-совместимости
  • нестабильной работе CDN-версий
  • невозможности корректного использования через <script> теги

Связанные конфигурационные элементы

Часто вместе с этой проблемой встречаются:

  • output.name (обязателен для UMD)
  • external
  • output.globals
  • preserveSymlinks
  • plugins: [nodeResolve()]

Но именно globals является ключевым элементом устранения предупреждения.

Поведенческая модель Rollup

Внутри генератора UMD логика можно упростить до следующего шага:

if (external module used in UMD/IIFE)
  if (no global mapping)
    warn MISSING_GLOBAL_NAME

Это не ошибка сборки, а сигнал о неполноте конфигурации.

Оглавление