Node Monorepo中ESLint import/no-unresolved问题排查与配置优化

一、import/no-unresolved 警告的核心问题及修复 #

1. ESLint 未关联子包的 TypeScript 配置 #

ESLint 的 import/resolver/typescript 插件需要明确指定各子包的 tsconfig.json 路径，否则无法解析子包内的模块和外部依赖（比如 React）。如果根目录 .eslintrc 缺少该配置，就会触发警告。

正确配置示例：

{
  "settings": {
    "import/resolver": {
      "typescript": {
        "project": ["./client/tsconfig.json", "./server/tsconfig.json"]
      }
    }
  }
}

2. 子包 TS 配置未设置模块解析根路径 #

每个子包的 tsconfig.json 需要配置 baseUrl 来定义子包内的模块根目录，让 ESLint 能识别相对路径或子包内绝对路径：

client/tsconfig.json：

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"] // 可选，用于子包内的别名导入
    }
  },
  "include": ["src/**/*"]
}

server/tsconfig.json 同理设置 baseUrl: "./src"。同时在根 .eslintrc 中同步扩展名配置：

{
  "settings": {
    "import/extensions": [".ts", ".tsx", ".js", ".jsx"]
  }
}

二、禁止跨子包导入与自动修复路径的配置 #

1. 拦截client/src或server/src这类非法路径 #

启用 import/no-absolute-path 规则禁止绝对路径导入跨子包内容，并通过 import/no-extraneous-dependencies 限制依赖范围：

{
  "rules": {
    "import/no-absolute-path": "error",
    "import/no-extraneous-dependencies": [
      "error",
      {
        "packageDir": ["./client/", "./server/"]
      }
    ]
  }
}

如果使用 npm/yarn workspaces，建议给子包命名（如@myrepo/client），允许通过包名合法导入，而非直接访问源码路径。

2. 自动修复非绝对导入路径 #

确保已安装必要插件：

npm install eslint-plugin-import @typescript-eslint/parser eslint-import-resolver-typescript --save-dev

启用 import/no-unresolved 的自动修复能力，同时在根 .eslintrc 中开启规则的修复支持（多数插件默认已配置）。子包的 .eslintrc 需继承根配置并指定本地 TS 配置：

{
  "extends": "../.eslintrc",
  "parserOptions": {
    "project": "./tsconfig.json"
  }
}

三、根目录执行 ESLint 的关键配置 #

根 .eslintrc 必须设置 root: true，确保 ESLint 从根目录开始解析配置，避免子包配置冲突。执行 npx eslint --fix . 时，ESLint 会自动遍历所有子包并应用修复规则。

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