Node.js+TypeScript项目ESLint无法解析路径别名问题求助

问题背景 #

在基于Node.js的TypeScript项目中，已在tsconfig.json中配置路径别名，但ESLint无法识别这些别名，持续报错：Unable to resolve path to module '@/config.js'。项目构建正常，但ESLint会标记下划线错误；尝试调整ESLint配置后，下划线错误消失，但执行npx eslint --fix .时出现新的类型错误。

项目环境 #

• Node.js版本：18.18.1
• TypeScript版本：5.2.1
• ESLint版本：8.54.0

现有配置 #

tsconfig.json #

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@sourceService/*": ["./src/modules/source/*"],
      "@crawlService/*": ["./src/modules/crawl/*"],
      "@searchService/*": ["./src/modules/search/*"],
      "@/*": ["./src/*"]
    },
    // ... 其他选项 ...
  },
  "include": ["./src/**/*", "./test"]
}

原始.eslintrc.json #

{
  "env": {
    "node": true
  },
  // ... 其他配置 ...
  "settings": {
    "import/parsers": {
      "@typescript-eslint/parser": [".ts", ".js"]
    },
    "import/resolver": {
      "node": true,
      "typescript": {
        "alwaysTryTypes": true,
        "project": "./"
      }
    }
  }
}

引发问题的导入语句 #

import { CONFIG } from '@/config.js';

已尝试的操作 #

• 确认已安装eslint-import-resolver-typescript依赖
• 配置ESLint启用TypeScript路径解析规则
• 重启ESLint服务及开发编辑器
• 验证src/config.js文件存在且路径正确

错误调整后的新问题 #

修改ESLint的settings配置如下后，下划线错误消失，但执行修复命令时出现报错：

"settings": {
    "import/parsers": {
      "node": {
        "paths": ["src"],
        "extensions": [".js", ".ts", ".d.ts", ".tsx"]
    },
      "@typescript-eslint/parser": [".ts", ".js"]
    },
    "import/resolver": {
      "typescript": true,
      "node": true
    }
  }

报错信息：

TypeError: "settings" for node must be an array
Occurred while linting C:\Users\...
Rule: "import/default"

正确配置方案 #

1. 确保安装必要依赖 #

如果尚未安装以下依赖，执行安装命令：

npm install -D eslint-plugin-import @typescript-eslint/parser eslint-import-resolver-typescript

2. 修正.eslintrc.json配置 #

替换为以下配置，重点修复路径解析器的配置逻辑：

{
  "env": {
    "node": true
  },
  "parser": "@typescript-eslint/parser",
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:import/recommended",
    "plugin:import/typescript"
  ],
  "settings": {
    "import/parsers": {
      "@typescript-eslint/parser": [".ts", ".js"]
    },
    "import/resolver": {
      "typescript": {
        "project": "./tsconfig.json", // 明确指定tsconfig路径，避免歧义
        "alwaysTryTypes": true
      },
      "node": {
        "extensions": [".js", ".ts"]
      }
    }
  }
}

3. 关键配置说明 #

• 明确tsconfig路径：将typescript解析器的project设为./tsconfig.json，而非./，确保ESLint能精准读取路径别名配置
• 移除错误的parser配置：不要在import/parsers中给node配置对象，node解析器的参数应放在import/resolver的node选项内
• 启用import插件的TS支持：在extends中加入plugin:import/recommended和plugin:import/typescript，让ESLint的import规则兼容TypeScript
• 规范导入后缀：建议导入语句中去掉.js后缀（TS会自动处理模块解析），若保留需确保文件实际存在（如src/config.js或src/config.ts）

4. 验证修复 #

• 重启编辑器或ESLint服务
• 执行npx eslint .检查是否还有路径解析错误
• 执行npx eslint --fix .验证修复命令正常运行

内容的提问来源于stack exchange，提问作者Wojciech Król