Решение типичных проблем с редактором

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

Понимание наиболее распространённых проблем позволяет быстро находить причину неисправности и восстанавливать корректную работу инструментов анализа кода.

ESLint не показывает ошибки в редакторе

Одна из самых распространённых ситуаций — выполнение команды ESLint в терминале успешно обнаруживает нарушения, однако редактор не отображает предупреждения и ошибки.

Возможные причины

Расширение ESLint не установлено

Во многих редакторах поддержка ESLint реализуется отдельным расширением.

Например, в Visual Studio Code требуется установка официального расширения ESLint.

Проверка:

npx eslint src/index.js

Если команда выводит ошибки, а редактор ничего не показывает, необходимо проверить состояние расширения.

Расширение отключено

После обновлений редактора или изменения рабочей области расширение может оказаться отключённым.

Необходимо убедиться, что:

  • расширение активно;
  • расширение разрешено для текущей рабочей области;
  • отсутствуют ограничения безопасности Workspace Trust.

Открыта не та директория проекта

ESLint ищет конфигурационные файлы относительно открытой папки.

Проблема часто возникает при следующей структуре:

workspace/
├── frontend/
│   ├── eslint.config.js
│   └── src/
└── backend/

Если открыт каталог:

workspace/

а конфигурация находится в:

workspace/frontend/

редактор может не обнаружить настройки ESLint.

Файл исключён из анализа

Проверяется наличие:

.eslintignore

или параметров:

ignores: [
    "dist/**",
    "build/**"
]

в конфигурации Flat Config.

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

ESLint работает в терминале, но не работает в VS Code

Подобная ситуация обычно связана с различиями между окружением редактора и терминала.

Проверка журнала ESLint

В VS Code полезно открыть:

View → Output → ESLint

Журнал часто содержит сообщения вида:

Failed to load ESLint library

или:

No ESLint configuration found

Именно эти сообщения позволяют быстро определить источник проблемы.

Неверная версия Node.js

Редактор может запускаться с одной версией Node.js, а терминал — с другой.

Например:

node -v

в терминале показывает:

v22.0.0

а расширение использует системную версию:

v16.0.0

В результате часть пакетов может не загружаться.

Особенно часто проблема возникает при использовании:

  • nvm;
  • fnm;
  • asdf;
  • Volta.

ESLint установлен только глобально

Нежелательно полагаться исключительно на глобальную установку:

npm install -g eslint

Предпочтительным считается локальное размещение:

npm install --save-dev eslint

Расширения редакторов обычно ищут ESLint внутри проекта.

Ошибка “Failed to load plugin”

Распространённая ошибка:

Failed to load plugin

или:

Cannot find module eslint-plugin-react

Причины

Плагин указан в конфигурации:

plugins: {
    react
}

но отсутствует в зависимостях:

npm install --save-dev eslint-plugin-react

Повреждённые зависимости

Иногда после обновлений возникает конфликт пакетов.

Помогает полная переустановка:

rm -rf node_modules
rm package-lock.json

npm install

Для Yarn:

rm -rf node_modules
rm yarn.lock

yarn install

Несовместимые версии

Например:

eslint@9
eslint-plugin-react@старой версии

Некоторые плагины могут не поддерживать новую архитектуру ESLint.

Следует проверить совместимость версий используемых пакетов.

Ошибка “No ESLint configuration found”

Сообщение:

No ESLint configuration found

означает, что ESLint не смог обнаружить конфигурацию.

Проверка Flat Config

Для современных версий ESLint рекомендуется наличие файла:

eslint.config.js

или:

eslint.config.mjs

Пример:

import js from "@eslint/js";

export default [
    js.configs.recommended
];

Неправильное расположение файла

Конфигурация должна находиться в корне проекта:

project/
├── eslint.config.js
├── package.json
└── src/

Если файл помещён внутрь:

config/eslint.config.js

ESLint может не найти его автоматически.

Конфликт между Prettier и ESLint

Иногда редактор постоянно изменяет файл после сохранения.

Например:

  1. ESLint исправляет код.
  2. Prettier форматирует файл иначе.
  3. ESLint снова пытается изменить результат.

Возникает цикл исправлений.

Симптомы

После сохранения:

const value = "test"

мгновенно превращается в:

const value = "test";

затем снова изменяется.

Решение

Использование пакета:

npm install --save-dev eslint-config-prettier

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

import eslintConfigPrettier from "eslint-config-prettier";

export default [
    eslintConfigPrettier
];

Он отключает правила ESLint, конфликтующие с Prettier.

Проверка настроек сохранения

Следует убедиться, что одновременно не работают несколько механизмов форматирования:

{
    "editor.formatOnSave": true
}

и

{
    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
    }
}

Неправильная комбинация настроек способна вызвать постоянные изменения файла.

Автоматическое исправление не работает

Команда:

npx eslint src --fix

успешно исправляет код, однако редактор этого не делает.

Причина

Не включён запуск исправлений при сохранении.

Для VS Code обычно используется настройка:

{
    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
    }
}

Правило не поддерживает исправление

Не каждое правило имеет механизм autofix.

Например:

if (foo == bar)

Некоторые правила могут лишь сообщить о проблеме:

eqeqeq

но не исправить её автоматически.

Файл открыт только для чтения

При отсутствии прав на запись исправления не применяются.

Симптомы:

  • предупреждения отображаются;
  • сохранение невозможно;
  • исправления отсутствуют.

ESLint не работает с TypeScript

Частая ошибка:

Parsing error

или:

Unexpected token interface

Отсутствует TypeScript Parser

Необходимы пакеты:

npm install --save-dev \
typescript \
typescript-eslint

Пример конфигурации:

import tseslint from "typescript-eslint";

export default [
    ...tseslint.configs.recommended
];

Не найден tsconfig.json

Некоторые правила требуют доступа к информации о типах.

При отсутствии файла:

tsconfig.json

редактор может выводить ошибки анализа.

Минимальный пример:

{
    "compilerOptions": {
        "strict": true
    }
}

Несколько tsconfig-файлов

В крупных проектах встречается структура:

tsconfig.json
tsconfig.app.json
tsconfig.test.json

Редактор может выбрать неверный файл конфигурации.

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

Проблемы в монорепозиториях

Структура:

repo/
├── packages/
│   ├── app/
│   └── ui/
└── eslint.config.js

создаёт дополнительные сложности.

ESLint анализирует только часть файлов

Причина может заключаться в шаблонах:

files: [
    "src/**/*.js"
]

которые не охватывают остальные пакеты.

Следует использовать более широкие шаблоны:

files: [
    "packages/*/src/**/*.js"
]

Редактор не находит конфигурацию

Если открыт каталог:

packages/app

а конфигурация находится в:

repo/eslint.config.js

редактор может не подняться до корня репозитория.

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

Дублирование ошибок

Иногда одна и та же проблема отображается несколько раз.

Пример:

ESLint
TypeScript
Language Server

одновременно сообщают о нарушении.

Причины

Параллельно работают:

  • встроенная проверка JavaScript;
  • TypeScript Language Service;
  • ESLint.

Способы устранения

Для Jav * aScript:

{
    "javascript.validate.enable": false
}

Для TypeScript:

{
    "typescript.validate.enable": false
}

После этого диагностика остаётся только у ESLint.

Медленная работа редактора

В больших проектах ESLint способен заметно замедлять работу среды разработки.

Анализ слишком большого количества файлов

Нежелательно проверять:

node_modules/
dist/
coverage/
build/

Пример игнорирования:

ignores: [
    "node_modules/**",
    "dist/**",
    "coverage/**"
]

Тяжёлые правила

Наибольшую нагрузку обычно создают:

  • правила, использующие информацию о типах TypeScript;
  • сложные импортные проверки;
  • анализ больших графов зависимостей.

В крупных проектах часть ресурсоёмких правил нередко запускается только в CI.

Большое количество одновременно открытых файлов

Каждый открытый файл может инициировать отдельный процесс проверки.

Симптомы:

  • задержка ввода текста;
  • повышенное потребление памяти;
  • высокая загрузка процессора.

Уменьшение количества открытых вкладок и оптимизация конфигурации обычно существенно улучшают производительность.

Проверка работоспособности ESLint

При возникновении сложных проблем полезно выполнять диагностику поэтапно.

Шаг 1. Проверка версии

npx eslint --version

Шаг 2. Проверка конфигурации

npx eslint --print-config src/index.js

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

Шаг 3. Проверка конкретного файла

npx eslint src/index.js

Шаг 4. Проверка редактора

Необходимо убедиться в наличии:

  • установленного расширения ESLint;
  • корректной версии Node.js;
  • локально установленного ESLint;
  • доступной конфигурации проекта.

Диагностический чек-лист

При отсутствии работы ESLint в редакторе последовательно проверяются следующие пункты:

  1. Установлен ли ESLint локально в проекте.
  2. Установлено ли расширение ESLint.
  3. Активно ли расширение.
  4. Найден ли файл eslint.config.js.
  5. Отсутствуют ли ошибки загрузки плагинов.
  6. Не попадает ли файл под правила игнорирования.
  7. Используется ли поддерживаемая версия Node.js.
  8. Работает ли ESLint через терминал.
  9. Нет ли конфликтов с Prettier.
  10. Не открыта ли неправильная директория проекта.
  11. Не возникает ли проблем с монорепозиторием.
  12. Не дублируются ли проверки другими инструментами анализа кода.

Систематическая проверка этих пунктов позволяет устранить подавляющее большинство проблем интеграции ESLint с современными редакторами кода.

Оглавление