使用TypeScript时ESLint无法识别Docusaurus别名的问题

问题分析 #

你遇到的错误是因为ESLint的import/no-unresolved规则无法识别Docusaurus内置的模块别名（如@docusaurus/Head、@theme/Layout）。虽然TypeScript能通过继承@tsconfig/docusaurus的配置解析这些别名，但ESLint需要额外配置才能同步识别逻辑。

你之前尝试的方案无效，核心原因是配置位置错误：import/no-unresolved的ignore选项应该定义在rules字段中，而非settings字段；且更合理的方式是让ESLint直接识别这些别名，而非忽略检查（忽略会丢失对其他导入路径的校验能力）。

解决方案 #

步骤1：安装ESLint TypeScript解析器依赖 #

安装eslint-import-resolver-typescript，它能让ESLint读取tsconfig.json中的别名配置，实现和TypeScript一致的路径解析：

npm install eslint-import-resolver-typescript --save-dev
# 或使用yarn
yarn add eslint-import-resolver-typescript -D

步骤2：修正ESLint配置 #

在你的ESLint配置文件（如.eslintrc.js或.eslintrc.json）中，添加解析器配置并调整规则：

示例：.eslintrc.js

module.exports = {
  // 其他原有配置...
  settings: {
    'import/resolver': {
      typescript: {
        // 指定项目的tsconfig文件路径
        project: './tsconfig.json',
      },
    },
  },
  rules: {
    'import/no-unresolved': [
      'error',
      {
        // 配置解析器后通常无需忽略，若仍有特殊别名可在此添加
        // ignore: ['^@theme/', '^@docusaurus/', '^@site/']
      },
    ],
  },
};

示例：.eslintrc.json

{
  "settings": {
    "import/resolver": {
      "typescript": {
        "project": "./tsconfig.json"
      }
    }
  },
  "rules": {
    "import/no-unresolved": [
      "error",
      {}
    ]
  }
}

步骤3：验证配置 #

重启ESLint服务（或重新运行ESLint校验命令），此时@docusaurus/Head、@theme/Layout这类别名的导入将不再触发import/no-unresolved错误。

补充说明 #

• @tsconfig/docusaurus/tsconfig.json已经内置了Docusaurus所需的全部别名配置，无需手动在项目的tsconfig.json中添加paths字段；
• 使用eslint-import-resolver-typescript后，ESLint会完全同步TypeScript的路径解析逻辑，比单纯忽略别名更可靠，还能保留对其他自定义导入路径的校验能力。

内容的提问来源于stack exchange，提问作者CeraMix