NestJS项目中ESLint无法解析符号链接目录@common别名的import/no-extraneous-dependencies问题排查

问题原因分析 #

你遇到的这个问题，本质是ESLint的import/no-extraneous-dependencies规则没把符号链接过来的@common目录识别为项目内部代码，反而误判成了外部npm包。虽说你在tsconfig.json里开了preserveSymlinks让TypeScript能正确解析别名，但ESLint的import插件有自己独立的依赖解析逻辑，和TypeScript的处理机制不互通，所以得单独适配符号链接场景。

解决方案 #

下面是几个可行的解决办法，你可以根据项目情况选择：

1. 调整import/no-extraneous-dependencies规则，允许@common相关导入

不用逐个把@common下的模块添加到import/core-modules，直接在规则配置里把@common的所有路径加入允许列表：

// .eslintrc.js 中的 rules 部分
'import/no-extraneous-dependencies': [
  'error',
  {
    devDependencies: [
      '**/*.e2e-spec.{js,ts}',
      '**/*.spec.{js,ts}',
      'test/**/*',
      '**/__mocks__/*',
    ],
    // 新增：允许@common下的所有内部导入
    allowedInternalDependencies: ['@common/**'],
    // 可选：如果@common指向项目根目录的common文件夹，也可以指定依赖查找目录包含它
    packageDir: [__dirname, __dirname + '/../common'],
  },
],

allowedInternalDependencies会告诉ESLint，@common开头的导入属于项目内部依赖，无需去npm包中查找。

2. 确保ESLint的TypeScript解析器能识别@common的别名映射

首先确认你的tsconfig.json里已经正确配置了@common的路径映射：

// tsconfig.json
{
  "compilerOptions": {
    // 其他配置
    "paths": {
      "@common/*": ["common/*"],
      "@utils/*": ["utils/*"],
      "@constants/*": ["constants/*"]
    },
    "preserveSymlinks": true
  }
}

然后在ESLint的settings里，让import/resolver.typescript正确读取这个路径配置；如果common目录有自己的tsconfig.json，也需要把它加入project列表：

// .eslintrc.js 中的 settings 部分
settings: {
  'import/resolver': {
    typescript: {
      alwaysTryTypes: true,
      // 如果common目录有独立的tsconfig，追加它的路径
      project: ['tsconfig.json', '../common/tsconfig.json'],
    },
  },
},

这样ESLint的TypeScript解析器就能和TypeScript编译器保持一致的别名解析逻辑。

3. 更新相关依赖版本

旧版本的@typescript-eslint/parser和eslint-import-resolver-typescript可能存在符号链接处理的bug，建议你把这些依赖更新到最新稳定版：

yarn upgrade @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-import-resolver-typescript

新版本对符号链接的兼容性更好，可能直接解决这个问题。

验证方案 #

修改配置后，运行yarn lint测试一下，如果@common的导入不再报错，就说明配置生效了。

内容来源于stack exchange