Настройка окружений: env

Параметр env в ESLint определяет предустановленные наборы глобальных переменных и правил окружения выполнения кода. Он влияет на то, какие идентификаторы считаются доступными без явного объявления, а также формирует контекст анализа для линтера.

Фактически env задаёт модель исполнения JavaScript-кода: браузер, Node.js, тестовые среды, ECMAScript-версии и специализированные платформы. При включении конкретного окружения ESLint автоматически добавляет соответствующие глобальные переменные в список разрешённых, снижая количество ложных срабатываний.

Базовая структура env

В классической конфигурации .eslintrc параметр env представляет собой объект, где ключи — названия окружений, а значения — логические флаги включения:

{
  "env": {
    "browser": true,
    "node": true
  }
}

Каждое включённое окружение расширяет набор глобальных переменных. Например, browser: true добавляет window, document, navigator, а node: true — require, module, process.

Основные встроенные окружения

browser

Активирует глобальные объекты веб-браузера:

  • window
  • document
  • navigator
  • location
  • fetch (в зависимости от среды выполнения)

Используется в клиентских приложениях, SPA и фронтенд-библиотеках.

node

Добавляет глобальные переменные Node.js:

  • process
  • Buffer
  • require
  • module
  • __dirname, __filename

Критично для серверных приложений, CLI-утилит и сборочных скриптов.

es6 / es2015

Включает поддержку глобальных сущностей и синтаксических особенностей ECMAScript 2015:

  • Promise
  • Map, Set, WeakMap, WeakSet
  • Symbol
  • стрелочные функции (в контексте анализа глобалов)

Важно учитывать, что es6 не включает поддержку модулей как глобалов, поскольку это регулируется parserOptions.

commonjs

Определяет окружение CommonJS:

  • require
  • exports
  • module

Часто используется в Node.js-проектах без ESM.

jest

Добавляет глобалы тестового фреймворка:

  • describe
  • test
  • expect
  • beforeEach, afterEach

Снижает необходимость ручного объявления тестовых функций.

mocha

Аналогично jest, но для Mocha:

  • describe
  • it
  • before, after
  • beforeEach, afterEach

jasmine

Поддерживает глобалы Jasmine:

  • describe
  • it
  • expect
  • spyOn

Влияние env на анализ кода

ESLint использует env для формирования списка допустимых глобальных переменных. При отсутствии соответствующего окружения любое обращение к неописанному идентификатору трактуется как ошибка:

console.log(window); // ошибка, если browser: false

После включения окружения:

{
  "env": {
    "browser": true
  }
}

тот же код становится валидным.

Совмещение нескольких окружений

env допускает одновременное включение нескольких контекстов исполнения:

{
  "env": {
    "browser": true,
    "node": true,
    "jest": true
  }
}

Такой подход характерен для универсальных приложений, где один и тот же код может выполняться в разных средах: например, при сервер-сайде рендеринге и последующем гидрировании на клиенте.

Связь env и ECMAScript-версий

Параметр env частично пересекается с parserOptions.ecmaVersion, но выполняет другую функцию:

  • env определяет глобальные переменные
  • parserOptions определяет синтаксическую поддержку

Пример:

{
  "env": {
    "es2022": true
  },
  "parserOptions": {
    "ecmaVersion": 2022
  }
}

Здесь es2022 добавляет глобалы и особенности среды, а ecmaVersion позволяет парсеру понимать современный синтаксис.

Пользовательские глобалы через env

Некоторые окружения позволяют расширять список глобальных переменных через отдельную настройку globals. Однако env сам по себе не предназначен для пользовательских значений, он работает только с предустановленными наборами.

Типичная комбинация:

{
  "env": {
    "browser": true
  },
  "globals": {
    "MyApp": "readonly"
  }
}

Поведение при конфликте окружений

Если несколько окружений определяют одно и то же имя глобальной переменной, ESLint объединяет их без конфликтов. При этом приоритет отсутствует: итоговый набор представляет собой объединение всех активных окружений.

Отключение окружений

Явное отключение выполняется через false:

{
  "env": {
    "browser": false,
    "node": true
  }
}

Это используется при миграции между средами или при строгом контроле глобального пространства имён.

Влияние на правила линтинга

Некоторые правила ESLint зависят от окружения. Например:

  • no-undef — проверяет использование неопределённых переменных
  • no-restricted-globals — ограничивает доступ к определённым глобалам

Без корректного env эти правила генерируют избыточные ошибки.

Flat config и современный подход

В новой системе конфигурации eslint.config.js концепция env заменяется более явной настройкой через languageOptions.globals.

Эквивалент классического browser:

export default [
  {
    languageOptions: {
      globals: {
        window: "readonly",
        document: "readonly",
        navigator: "readonly"
      }
    }
  }
];

Тестовые окружения также подключаются через готовые пакеты глобалов.

Практическое поведение в многофайловых проектах

В проектах с несколькими точками входа env может задаваться на уровне:

  • всего проекта
  • отдельных директорий
  • конкретных файлов через overrides

Пример:

{
  "env": {
    "browser": true
  },
  "overrides": [
    {
      "files": ["server/**/*.js"],
      "env": {
        "node": true,
        "browser": false
      }
    }
  ]
}

Такой подход позволяет разделять клиентский и серверный код без изменения основной конфигурации.

Типичные ошибки конфигурации env

  • одновременное использование несовместимых окружений без необходимости, приводящее к избыточным глобалам
  • отсутствие нужного окружения, вызывающее ложные ошибки no-undef
  • ожидание, что env включает синтаксис языка (эта функция принадлежит parserOptions)
  • использование устаревших окружений без понимания их влияния на глобальные переменные

Роль env в архитектуре линтинга

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

Параметр env выступает слоем абстракции над глобальной областью видимости, стандартизируя её для разных типов JavaScript-приложений.

Оглавление