ESLint で ignore 指定したファイルが無視されない

要約

ESLint で「無視したはずのファイルがチェックされる」原因の大半は、v9 の flat config 移行に伴うもの。
v9 では .eslintignore を読まなくなり、eslint.config.js の ignores キーが唯一の指定方法。
グローバル無視にしたい場合は files を併記せず { ignores: [...] } 単独のオブジェクトで書く。glob は ** の有無や否定パターンの順序に注意する。

よくある原因

1. リポジトリを ESLint v9 にアップグレードしたが、.eslintignore を残したまま運用している。
   v9 はこのファイルを参照しない。
2. eslint.config.js の途中に { files: ["src/**/*.ts"], ignores: ["src/legacy/**"] } のように書いてしまい、src/legacy/** のチェックを「特定ルール構成から外す」だけになっていて、ESLint 全体のスキャン対象からは外れていない。
3. ディレクトリを dist とだけ書いても、それは「dist という名前のファイル」にしかマッチしない。
   配下まで除外したいなら dist/**。
4. eslint src/a.ts のように除外対象のファイルを直接渡すと File ignored because of a matching ignore pattern. という 警告だけが出る。
   ファイル自体は lint されておらず終了コードも 0 だが、CI ログにファイル名が並ぶので「無視されていないように見える」原因になる。

解決策

1. flat config でグローバル ignore を書く

// eslint.config.js
export default [
  { ignores: ["dist/**", "coverage/**", "**/*.generated.ts"] },
  // ... 他の設定オブジェクト
];

ignores 単独のオブジェクトはグローバルに作用する（公式ドキュメント（新しいタブで開く）↗）。files を併記すると、その files で絞り込んだ範囲内の局所 ignore になってしまう。

2. パターンの粒度を直す

ignores: [
  "node_modules/**",
  "dist/**",
  "**/__generated__/**",
  "!src/important.generated.ts" // 例外で含めたいファイルは ! を後ろに
]

否定パターン（!）は 後段 に置く。
順序を逆にすると効かない。

3. legacy 設定を維持する場合

package.json で eslint@^8 のままなら .eslintignore は有効。
ただしルートからの相対パスで書く必要があり、サブパッケージ単位の ignore は各ディレクトリに .eslintignore を置く。

4. CLI に渡すファイルを絞る

$ npx eslint dist/bundle.js
  0:0  warning  File ignored because of a matching ignore pattern. Use "--no-ignore" to disable file ignore settings or use "--no-warn-ignored" to suppress this warning
✖ 1 problem (0 errors, 1 warning)

直接渡しても除外対象なら lint はされない。
警告が邪魔なら --no-warn-ignored、逆に除外を無効化して検査したいなら --no-ignore を付ける。npm run lint のスクリプトを eslint . にしておけば、そもそもこの警告は出ない。

実行例

実際に上記の手順を node:20 環境で動かすと、.eslintignore に dist を記載した状態で eslint . を実行した際に ESLintIgnoreWarning が出力されて同ファイルは無視されず、dist/generated.js の no-unused-vars エラーが検出されて終了コード 1 となる一方、eslint.config.js の ignores 単独オブジェクトへ切り替えると終了コード 0 で dist が正しく除外されることが確認できる。

v9.39.5

$ npx eslint .
(node:115) ESLintIgnoreWarning: The ".eslintignore" file is no longer supported. Switch to using the "ignores" property in "eslint.config.js": https://eslint.org/docs/latest/use/configure/migration-guide#ignoring-files
(Use `node --trace-warnings ...` to show where the warning was created)
 
/tmp/tmp.Ag4ukRXSTB/dist/generated.js
  1:7  error  'unused' is assigned a value but never used  no-unused-vars
 
✖ 1 problem (1 error, 0 warnings)
 
eslint の終了コード: 1

$ npx eslint .
eslint の終了コード: 0（0 = dist が無視された）

— 2026-08-02 時点の出力