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

Одной из наиболее частых причин проблем с ESLint является смешивание разных форматов конфигурации. В экосистеме существует два основных подхода: legacy-конфигурация (.eslintrc.*) и flat config (eslint.config.js).

Типичные ошибки:

  • одновременное использование .eslintrc и eslint.config.js
  • попытка применять старые ключи в flat config
  • миграция без удаления legacy-файлов

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

Ошибки в поле extends

Поле extends часто используется неправильно, особенно при подключении нескольких конфигураций.

Проблемные сценарии:

{
  "extends": ["eslint:recommended", "plugin:react/recommended", "airbnb"]
}

Ошибки возникают, когда:

  • порядок extends нарушает приоритеты
  • отсутствует установленный пакет конфигурации
  • используется несовместимая версия shareable config

Ключевая причина: ESLint загружает конфигурации последовательно, и последующие значения могут перезаписывать предыдущие, включая правила и parserOptions.

Отсутствующие или несовместимые плагины

Одна из самых «тихих» ошибок — отсутствие установленного плагина при его использовании в конфиге.

{
  "plugins": ["react", "import"]
}

Но пакет не установлен:

npm ERR! Failed to load plugin 'react'

Причины:

  • забыли установить eslint-plugin-*
  • установленная версия плагина не поддерживает текущую версию ESLint
  • монорепозиторий не пробрасывает зависимости

Некорректный parser

ESLint по умолчанию использует встроенный парсер, но в современных проектах часто требуется @babel/eslint-parser или @typescript-eslint/parser.

Ошибка конфигурации:

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2020
  }
}

Проблемы возникают, когда:

  • parser установлен, но не совпадает версия TypeScript
  • отсутствует tsconfig.json
  • не указан project в parserOptions

Особенно критично для TypeScript:

{
  "parserOptions": {
    "project": "./tsconfig.json"
  }
}

Без этого ESLint теряет типовую информацию и часть правил перестаёт работать.

Ошибки parserOptions

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

Частые проблемы:

  • ecmaVersion ниже используемой версии JavaScript
  • отсутствует sourceType: "module"
  • не включены JSX-фичи
{
  "parserOptions": {
    "ecmaVersion": 2015,
    "sourceType": "script"
  }
}

Последствия:

  • import/export вызывают ошибки
  • optional chaining не распознаётся
  • async/await считается синтаксической ошибкой

Конфликт правил между конфигурациями

При использовании нескольких источников конфигурации часто возникает ситуация, когда правила «перетирают» друг друга.

Пример:

{
  "rules": {
    "no-console": "error"
  },
  "extends": ["eslint:recommended"]
}

И в другом конфиге:

{
  "rules": {
    "no-console": "off"
  }
}

Причина: ESLint применяет последний загруженный источник конфигурации, и порядок становится критически важным.

Ошибки в env

Поле env определяет глобальные переменные среды выполнения.

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

Типичные проблемы:

  • отключён browser, но используется window
  • не включён node, но используется process
  • забыли включить es2021, es2022

Результат: ESLint начинает выдавать ошибки о несуществующих переменных.

Неправильное использование globals

Иногда разработчики пытаются вручную объявить глобальные переменные:

{
  "globals": {
    "MY_API": "readonly"
  }
}

Ошибки:

  • переменные объявлены как writable без необходимости
  • конфликт с env
  • дублирование глобалов из eslint-env

Последствия:

  • правила типа no-undef перестают работать корректно
  • появляются ложные отрицания или пропуски ошибок

Проблемы с overrides

overrides часто используются для разделения конфигурации по типам файлов.

{
  "overrides": [
    {
      "files": ["*.test.js"],
      "rules": {
        "no-unused-expressions": "off"
      }
    }
  ]
}

Типичные ошибки:

  • неправильные glob-паттерны
  • перекрытие глобальных правил без понимания приоритета
  • отсутствие files, из-за чего override применяется ко всему проекту

Игнорирование файлов (ignorePatterns и .eslintignore)

Ошибки в игнорировании приводят либо к избыточной проверке, либо к её отсутствию.

Типичные проблемы:

  • конфликт между .eslintignore и ignorePatterns
  • игнорирование dist/, но не build/
  • случайное исключение исходного кода
{
  "ignorePatterns": ["dist", "node_modules"]
}

Последствие: линтер либо тормозит, либо не проверяет нужные файлы.

Несовместимость версий ESLint и плагинов

Экосистема ESLint сильно зависит от версии ядра.

Типичные сценарии:

  • ESLint 9 + старые плагины
  • eslint-plugin-react без поддержки новых AST
  • TypeScript parser старой версии

Симптомы:

  • Definition for rule not found
  • Cannot read properties of undefined
  • тихое игнорирование правил

Ошибки flat config (ESLint 9+)

Flat config вводит принципиально новый формат:

export default [
  {
    files: ["**/*.js"],
    rules: {
      semi: "error"
    }
  }
]

Типичные ошибки миграции:

  • попытка использовать extends
  • использование .eslintrc ключей
  • неправильное подключение plugins как строк

Причина проблем: flat config требует явного импорта плагинов:

import js from "@eslint/js";

export default [
  js.configs.recommended
]

Ошибки в rules конфигурации

Неправильная структура правил — частый источник ошибок.

{
  "rules": {
    "quotes": ["error", "double", "unexpected-extra"]
  }
}

Проблемы:

  • лишние параметры
  • неправильный тип значения ("error" вместо 2)
  • неверные аргументы правила

Результат: ESLint падает при загрузке конфигурации.

Неправильное подключение TypeScript-правил

{
  "extends": [
    "plugin:@typescript-eslint/recommended"
  ]
}

Ошибки возникают, когда:

  • не установлен typescript
  • отсутствует @typescript-eslint/eslint-plugin
  • используется JS-файл без parser

Конфликты Prettier и ESLint

Частая причина «странного поведения» линтера.

Проблема: ESLint и Prettier начинают спорить о форматировании.

{
  "extends": ["eslint:recommended", "prettier"]
}

Ошибки конфигурации:

  • отсутствие eslint-config-prettier
  • включённые stylistic rules ESLint одновременно с Prettier
  • двойное форматирование

Неправильный root в legacy конфигурации

{
  "root": false
}

Последствия:

  • ESLint поднимается вверх по директориям
  • подключаются чужие конфиги
  • правила неожиданно изменяются

Ошибки при работе в монорепозиториях

Монорепозитории усиливают конфигурационные проблемы.

Типичные ошибки:

  • отсутствует overrides для пакетов
  • плагины не резолвятся из корня
  • разные версии ESLint в workspace

Симптомы:

  • одинаковый файл линтится по-разному
  • часть пакетов игнорируется
  • ошибки появляются только в CI

Неправильная настройка settings

{
  "settings": {
    "react": {
      "version": "detect"
    }
  }
}

Ошибки:

  • плагин не поддерживает settings
  • неверные ключи конфигурации
  • отсутствие автоматического определения версии

Проблемы с путями и резолвингом

ESLint использует Node resolution, и ошибки путей встречаются часто.

Типичные ситуации:

  • "plugin": "./plugins/eslint-plugin-custom"
  • alias не работает без настройки import/resolver
  • monorepo workspace не видит локальные плагины

Неправильная интерпретация ошибок ESLint

Часто проблема не в конфигурации, а в неверном понимании сообщения:

  • «rule not found» → плагин не загружен
  • «parser error» → неверный parserOptions
  • «definition missing» → конфликт версий
  • «unexpected token» → неподдерживаемый ecmaVersion

Системные причины нестабильной конфигурации

На уровне архитектуры проекта ошибки возникают из-за:

  • отсутствия единого ESLint config слоя
  • дублирования конфигураций в пакетах
  • смешивания legacy и modern подходов
  • отсутствия фиксации версий зависимостей
Оглавление