三斜线引用声明文件触发ESLint错误，改用import/配置失败求助

针对你遇到的三斜线引用有效但ESLint报错、其他加载方式失效的情况，给你几个可行的解决办法：

1. 局部禁用ESLint规则 #

在使用三斜线引用的文件里，给对应行加禁用注释，精准解决单文件报错：

// eslint-disable-next-line @typescript-eslint/triple-slash-reference
/// <reference path="../declarations.d.ts" />

如果文件内有多个三斜线引用，也可以在文件顶部一次性禁用该规则：

/* eslint-disable @typescript-eslint/triple-slash-reference */
/// <reference path="../declarations.d.ts" />
// 其他代码...

2. 适配NX的tsconfig配置+清除缓存 #

NX的缓存和配置层级可能导致声明文件未被识别，试试这两步：

• 把自定义声明文件放到项目的src/types目录下，在项目级tsconfig.json的include数组中添加：

  "include": [
    "src/**/*",
    "src/types/**/*.d.ts"
  ]
  

  或者在根级tsconfig.base.json里配置typeRoots：

  "typeRoots": ["node_modules/@types", "./src/types"]
  

• 执行nx reset清除NX缓存，再重新运行构建命令。

3. 修改声明文件为模块格式，兼容import方式 #

给声明文件添加空导出，让TS将其识别为模块，这样import就能生效：

import '@types/my-react-package';

declare module '@types/my-react-package' {
  export interface PackageProps {
    showPreview?: boolean;
  }
}

// 添加空导出，标记为模块
export {};

之后在需要的文件里用import '../declarations.d.ts';，同时确保该文件被tsconfig的include字段包含。

4. 调整ESLint规则配置（团队允许的情况下） #

在项目的.eslintrc.json里修改规则，允许path类型的三斜线引用：

{
  "rules": {
    "@typescript-eslint/triple-slash-reference": [
      "error",
      {
        "path": "always",
        "types": "prefer-import",
        "lib": "always"
      }
    ]
  }
}

这样既保留ESLint对其他类型三斜线引用的检查，又允许你用path引用自定义声明文件。

内容的提问来源于stack exchange，提问作者sir-haver