Игнорирование файлов и директорий: .eslintignore

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

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

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

  • зависимости в node_modules
  • собранные артефакты dist, build
  • автогенерируемые файлы
  • сторонние библиотеки, включённые в репозиторий
  • временные файлы и кеши

Исключение этих данных снижает нагрузку на анализ и предотвращает ложные срабатывания на код, который не предназначен для ручного сопровождения.

Синтаксис файла .eslintignore

Файл .eslintignore использует синтаксис, близкий к .gitignore, включая поддержку glob-паттернов.

Базовые правила

Каждая строка — отдельный шаблон:

node_modules/
dist/
build/
  • node_modules/ — исключает всю директорию
  • dist/ — исключает сборку проекта
  • build/ — исключает результаты компиляции

Пустые строки игнорируются. Комментарии начинаются с #:

# зависимости
node_modules/

# сборка
dist/

Глоб-паттерны

Поддерживаются символы:

  • * — любое количество символов в пределах одного сегмента
  • ** — рекурсивное совпадение по директориям
  • ? — один символ

Примеры:

**/*.min.js
src/**/temp/
**/*.test.js
  • **/*.min.js — все минифицированные файлы в проекте
  • src/**/temp/ — любые папки temp внутри src
  • **/*.test.js — тестовые файлы во всех директориях

Относительные пути и базовая директория

Паттерны в .eslintignore интерпретируются относительно директории, где расположен файл. Обычно это корень проекта.

project/
  .eslintignore
  src/
  dist/

Паттерн dist/ будет соответствовать project/dist/.

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

Инверсия правил

Поддерживается исключение из игнора через !:

dist/
!dist/important-file.js

Здесь вся директория dist игнорируется, кроме указанного файла.

Инверсия работает только если предыдущий паттерн уже исключил область. Если файл не попадает под игнор, ! не имеет эффекта.

Взаимодействие с CLI ESLint

ESLint применяет .eslintignore автоматически при запуске:

eslint .

Можно переопределить игнорирование через флаги:

  • --no-ignore — отключает игнорирование
  • --ignore-path — задаёт альтернативный файл игнора

Пример:

eslint . --ignore-path .customignore

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

Система игнорирования ESLint включает несколько уровней:

  1. .eslintignore
  2. ignorePatterns в конфигурации
  3. встроенные исключения (например, node_modules в некоторых режимах)
  4. флаги CLI

Если используются несколько источников, они объединяются в единое правило исключений.

Современное состояние и Flat Config

В ESLint Flat Config (начиная с ESLint 8+ и особенно актуально в ESLint 9) механизм .eslintignore считается устаревающим в пользу явной конфигурации через ignores.

Пример flat config:

export default [
  {
    ignores: [
      "node_modules/**",
      "dist/**",
      "**/*.min.js"
    ]
  }
];

В этом формате:

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

Тем не менее .eslintignore продолжает поддерживаться для обратной совместимости.

Отличие .eslintignore от ignorePatterns

ignorePatterns задаётся внутри конфигурации ESLint:

module.exports = {
  ignorePatterns: ["dist/", "build/"]
};

Основные различия:

  • .eslintignore — внешний файл, независимый от конфигурации
  • ignorePatterns — часть конфигурации проекта
  • Flat config заменяет оба подхода через ignores

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

Особенности обработки путей

ESLint нормализует пути перед сравнением:

  • приводит \ к / на Windows
  • удаляет избыточные сегменты (./, ../ где возможно)
  • сравнивает с использованием POSIX-стиля

Пример:

src//utils///helpers.js

будет интерпретирован как:

src/utils/helpers.js

Игнорирование и производительность

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

  • уменьшение числа файлов снижает время обхода
  • исключение node_modules предотвращает экспоненциальный рост анализа
  • фильтрация build-артефактов уменьшает IO-нагрузку

В проектах с тысячами файлов корректно настроенный .eslintignore может сокращать время проверки в несколько раз.

Типичные паттерны игнорирования

Часто используемые шаблоны:

node_modules/
coverage/
dist/
build/
logs/
*.min.js
*.bundle.js

Также часто исключаются:

  • .cache/
  • .next/
  • .nuxt/
  • .parcel-cache/

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

Распространённые проблемы:

Игнорирование исходного кода

Иногда чрезмерно широкие паттерны исключают реальные исходники:

src/**

Это приводит к тому, что ESLint фактически не анализирует проект.

Конфликт игнора и lint-staged

При использовании lint-staged игнор может дублировать фильтрацию, что приводит к неожиданному пропуску файлов.

Неправильные относительные пути

Паттерны без учёта структуры проекта:

/dist

может не совпадать с ожидаемым dist/, если интерпретация пути отличается.

Поведение с уже переданными файлами

Если файл явно передан в CLI:

eslint src/app.js

и он попадает под .eslintignore, он всё равно может быть проигнорирован. Однако флаг --no-ignore переопределяет это поведение.

Комбинация с overrides

Хотя .eslintignore исключает файлы полностью, overrides в конфигурации ESLint не могут «вернуть» файл из игнора. Для этого используется инверсия или изменение конфигурации игнорирования.

Эволюция подхода к игнорированию

Исторически .eslintignore был основным механизмом исключения файлов, но развитие ESLint привело к смещению в сторону:

  • явной конфигурации
  • программируемых правил
  • flat config

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

Роль в монорепозиториях

В монорепозиториях .eslintignore часто применяется на уровне корня:

packages/
apps/
dist/
node_modules/

Однако при сложной структуре предпочтительнее локальные ignores в flat config, поскольку они позволяют задавать разные правила для отдельных пакетов.

Влияние на инструменты экосистемы

Инструменты, интегрированные с ESLint:

  • редакторы (VS Code)
  • CI пайплайны
  • pre-commit хуки

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

Оглавление