ESLint のデバッグ方法：想定外のエラーを調査する

2025年7月24日

ESLint

ESLint は JavaScript や TypeScript のコード品質を保つための強力なツールですが、時には想定外のエラーに遭遇することがあります。この記事では、ESLint のエラーを効率的にデバッグし、解決するための段階的なアプローチをご紹介します。

ESLint のエラーに悩まされている開発者の方々にとって、この記事が問題解決の一助となることを願っています。実際のエラーコードと解決策を通じて、ESLint の内部動作を理解し、より自信を持って開発を進められるようになるでしょう。

ESLint エラーの種類と特徴

ESLint のエラーは大きく 4 つのカテゴリに分類できます。それぞれの特徴を理解することで、適切な対処法を選択できるようになります。

構文エラー（Syntax Error）

構文エラーは、ESLint がコードを解析できない場合に発生します。最も基本的なエラータイプです。

javascript// 構文エラーの例
const example = {
  name: "test"
  // カンマが抜けている
  age: 25
}

このような場合、ESLint は以下のようなエラーを出力します：

arduinoSyntaxError: Unexpected token (4:1)
  2 | const example = {
  3 |   name: "test"
> 4 |   age: 25
    | ^
  5 | }

構文エラーは通常、コードエディタでも赤い波線で表示されるため、比較的発見しやすいエラーです。

ルール違反（Rule Violation）

ESLint の設定されたルールに違反した場合に発生するエラーです。最も頻繁に遭遇するエラータイプです。

javascript// ルール違反の例
var oldVariable = 'ES5 style'; // no-varルール違反
console.log('debug message'); // no-consoleルール違反

エラーメッセージの例：

javascripterror  Unexpected var, use let or const instead  no-var
error  Unexpected console statement             no-console

ルール違反は、ESLint の設定ファイル（.eslintrc.jsなど）で制御できるため、プロジェクトの要件に応じて調整可能です。

設定ファイルの問題

ESLint の設定ファイル自体に問題がある場合のエラーです。

javascript// 問題のある設定ファイル例
module.exports = {
  extends: [
    'eslint:recommended',
    'non-existent-config', // 存在しない設定
  ],
  rules: {
    'invalid-rule': 'error', // 存在しないルール
  },
};

この場合、以下のようなエラーが発生します：

vbnetESLint: Cannot find module 'eslint-config-non-existent-config'
Error: Definition for rule 'invalid-rule' was not found

設定ファイルの問題は、ESLint の起動時や設定読み込み時に発生するため、早期に発見できます。

プラグイン関連のエラー

ESLint プラグインの設定や互換性の問題で発生するエラーです。

javascript// プラグイン設定の問題例
module.exports = {
  plugins: ['@typescript-eslint'],
  parser: '@typescript-eslint/parser',
  rules: {
    '@typescript-eslint/no-unused-vars': 'error',
  },
};

プラグインが正しくインストールされていない場合：

vbnetESLint: Cannot find module 'eslint-plugin-typescript-eslint'
Error: Failed to load plugin '@typescript-eslint'

プラグイン関連のエラーは、依存関係の管理が重要になります。

基本的なデバッグ手順

ESLint のエラーを効率的に解決するためには、体系的なアプローチが重要です。以下の手順で進めることで、問題の根本原因を特定できます。

エラーメッセージの読み方

ESLint のエラーメッセージには、問題解決に必要な情報が含まれています。

luaerror  'example' is assigned a value but never used  no-unused-vars
      ^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^
      |        |                                    |
      |        |                                    +-- ルール名
      |        +-- エラーの説明
      +-- 問題のある変数名

エラーメッセージの構造を理解することで、どのファイルのどの行で何が問題なのかを素早く把握できます。

ログレベルの確認方法

ESLint の詳細なログを確認することで、問題の原因を特定できます。

bash# 詳細なログを出力
yarn eslint --debug src/

# 特定のファイルの詳細ログ
yarn eslint --debug --print-config src/components/Example.js

デバッグモードでは、以下のような情報が出力されます：

vbnetESLint: Loaded config from /path/to/.eslintrc.js
ESLint: Loaded plugin '@typescript-eslint'
ESLint: Parsing /path/to/file.ts with parser @typescript-eslint/parser

この情報により、設定ファイルの読み込み状況やプラグインの動作を確認できます。

設定ファイルの検証

設定ファイルが正しく読み込まれているかを確認する方法です。

bash# 設定ファイルの内容を表示
yarn eslint --print-config src/index.js

出力例：

javascript{
  "env": {
    "browser": true,
    "es2021": true
  },
  "extends": [
    "eslint:recommended",
    "@typescript-eslint/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "plugins": ["@typescript-eslint"],
  "rules": {
    "no-unused-vars": "off",
    "@typescript-eslint/no-unused-vars": "error"
  }
}

この出力により、実際に適用されている設定を確認できます。

高度なデバッグテクニック

基本的なデバッグ手順では解決できない問題に対して、より高度なテクニックを活用します。

--debug フラグの活用

--debugフラグを使用することで、ESLint の内部動作を詳細に確認できます。

bash# デバッグ情報をファイルに出力
yarn eslint --debug src/ > eslint-debug.log 2>&1

# 特定のルールのデバッグ
yarn eslint --debug --rule 'no-unused-vars: error' src/

デバッグログには以下のような情報が含まれます：

vbnetESLint: Loaded config from /path/to/.eslintrc.js
ESLint: Loaded plugin '@typescript-eslint'
ESLint: Loaded plugin 'react'
ESLint: Parsing /path/to/file.ts with parser @typescript-eslint/parser
ESLint: Linting /path/to/file.ts
ESLint: Applying rule 'no-unused-vars' to /path/to/file.ts

この情報により、どのプラグインが読み込まれ、どのルールが適用されているかを追跡できます。

カスタムルールのデバッグ

カスタムルールを作成している場合のデバッグ方法です。

javascript// カスタムルールのデバッグ例
module.exports = {
  meta: {
    type: 'suggestion',
    docs: {
      description: 'Custom rule for debugging',
    },
  },
  create(context) {
    return {
      Identifier(node) {
        // デバッグ用のログ出力
        console.log('Processing identifier:', node.name);

        if (node.name === 'debug') {
          context.report({
            node,
            message: "Avoid using 'debug' as identifier",
          });
        }
      },
    };
  },
};

カスタムルールのデバッグでは、console.logやdebugger文を活用して、ルールの動作を確認します。

パフォーマンス問題の調査

ESLint の実行が遅い場合の調査方法です。

bash# パフォーマンス測定
yarn eslint --debug --timing src/

# 特定のファイルの処理時間を確認
yarn eslint --debug --cache src/

パフォーマンス問題の原因として、以下が考えられます：

大量のファイルの処理
複雑なルールの適用
プラグインの処理時間
キャッシュの未活用

よくある問題と解決策

実際の開発現場で頻繁に遭遇する問題とその解決策をご紹介します。

設定ファイルの競合

複数の設定ファイルが存在する場合の競合問題です。

javascript// .eslintrc.js
module.exports = {
  extends: ['eslint:recommended'],
  rules: {
    'no-console': 'error',
  },
};

// .eslintrc.local.js（ローカル設定）
module.exports = {
  rules: {
    'no-console': 'warn', // 競合が発生
  },
};

解決策：

javascript// 設定の優先順位を明確にする
module.exports = {
  extends: ['eslint:recommended'],
  rules: {
    'no-console':
      process.env.NODE_ENV === 'production'
        ? 'error'
        : 'warn',
  },
};

設定ファイルの競合を避けるため、環境変数や条件分岐を活用して動的に設定を調整します。

プラグインの互換性問題

プラグインのバージョン不整合による問題です。

json// package.jsonの依存関係
{
  "devDependencies": {
    "eslint": "^8.0.0",
    "@typescript-eslint/eslint-plugin": "^5.0.0",
    "@typescript-eslint/parser": "^6.0.0" // バージョン不整合
  }
}

解決策：

bash# プラグインのバージョンを統一
yarn add -D @typescript-eslint/eslint-plugin@^6.0.0 @typescript-eslint/parser@^6.0.0

# 依存関係の確認
yarn why @typescript-eslint/eslint-plugin

プラグインの互換性問題は、バージョンの統一と依存関係の確認で解決できます。

環境固有の問題

開発環境や CI 環境での違いによる問題です。

javascript// 環境別の設定例
module.exports = {
  env: {
    browser: process.env.NODE_ENV === 'browser',
    node: process.env.NODE_ENV === 'node',
  },
  rules: {
    'no-process-env':
      process.env.NODE_ENV === 'browser' ? 'error' : 'off',
  },
};