在 TypeScript 中配置跳过指定库的类型检查

在 TypeScript 项目中，有时需要跳过对某些库的类型检查，尤其是在处理第三方库时，其类型定义可能不完整、存在冲突，或者为了加快编译速度。虽然可以使用 // @ts-ignore 或 // @ts-nocheck 在代码中临时跳过类型检查，但这种方法需要在多个地方手动添加，较为繁琐。为了更高效地管理类型检查，可以通过配置 tsconfig.json 文件来实现全局或特定范围的类型检查跳过。以下是详细的配置方法和相关说明。

使用 tsconfig.json 配置跳过类型检查

tsconfig.json 文件是 TypeScript 项目的核心配置文件，通过修改其中的字段，可以灵活地控制 TypeScript 编译器的行为，包括类型检查。以下是一些常用的配置方法，可以帮助你跳过指定库的类型检查。

1. skipLibCheck：跳过所有声明文件的类型检查

skipLibCheck 是一个全局性的配置选项，当设置为 true 时，TypeScript 编译器会跳过对所有声明文件（.d.ts 文件）的类型检查。这包括第三方库提供的类型定义文件，通常位于 node_modules/@types 目录下。启用此选项可以显著提高编译速度，并避免因第三方库的类型定义问题导致的错误。

配置方法：

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}
  

适用场景：

• 第三方库的类型定义不完整或存在冲突。
• 项目依赖大量第三方库，导致编译时间过长。
• 你信任第三方库的类型定义，或者暂时不需要对其进行严格检查。

优点：

• 显著提高编译速度，尤其是在大型项目中。
• 避免因第三方库类型定义问题导致的编译错误。

缺点：

• 降低类型安全性，可能会掩盖潜在的类型错误。
• 如果第三方库的类型定义存在问题，可能会在运行时引发错误。

官方文档：https://www.typescriptlang.org/tsconfig/skipLibCheck.html

2. exclude：排除特定文件或目录

exclude 选项允许你指定 TypeScript 编译器应该忽略的文件或目录。通过将某些库或文件夹添加到 exclude 数组中，可以避免对这些文件进行类型检查和编译。

配置方法：

{
  "compilerOptions": {
    // ...其他配置
  },
  "exclude": [
    "node_modules/some-library",
    "node_modules/another-library",
    "path/to/your/library"
  ]
}
  

适用场景：

• 完全排除某些库或文件夹的类型检查。
• 某些库的类型定义存在问题，且无法修改这些库。

注意事项：

• exclude 会完全忽略指定路径下的文件和文件夹，包括 .ts 和 .d.ts 文件。
• 如果排除的文件是项目的一部分，可能会导致运行时错误。
• 如果你的代码中显式导入了被 exclude 的文件或库，这些文件仍然会被 TypeScript 处理。因此，exclude 仅适用于那些不直接导入的文件。
• 如果 tsconfig.json 文件中同时使用了 include 和 exclude，exclude 的作用是从 include 的结果中排除指定的文件。

官方文档：https://www.typescriptlang.org/tsconfig/exclude.html

3. typeAcquisition.exclude：排除特定模块的类型获取

typeAcquisition 是一个高级配置选项，主要用于控制 TypeScript 的自动类型获取功能。通过 typeAcquisition.exclude，你可以禁用某些模块的类型获取，从而跳过这些模块的类型检查。这在 JavaScript 项目中，或者当你使用 TypeScript 的自动类型获取功能时非常有用。

配置方法：

{
  "typeAcquisition": {
    "exclude": ["library-name", "jest", "mocha"]
  }
}
  

适用场景：

• 你正在使用 JavaScript 项目，并启用了自动类型获取功能。
• 某些库的类型定义与你的项目冲突，但你不想跳过所有声明文件的类型检查。
• 你不需要对某些测试工具或辅助库进行类型检查。

官方文档：https://www.typescriptlang.org/tsconfig#typeAcquisition

4. typeRoots 和 types：自定义类型声明的加载路径

typeRoots 选项允许你指定 TypeScript 查找类型定义的目录。默认情况下，TypeScript 会从 node_modules/@types 目录下加载类型声明。通过自定义 typeRoots，你可以控制哪些类型定义文件被加载，从而跳过某些库的类型检查。types 选项则允许你指定需要包含的类型声明包，并可以通过在包名前添加 ! 来排除特定的类型声明包。

配置方法：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./custom-types"],
    "types": ["jquery", "node", "!third-party-library"]
  }
}
  

适用场景：

• 当你希望自定义类型定义的加载路径时。
• 当你希望跳过某些库的类型定义时。
• 当你需要排除特定库的类型声明时。

注意事项：

• typeRoots 会覆盖默认的类型定义查找路径（node_modules/@types），因此需要确保所有需要的类型定义文件都在指定的路径中。
• 在 types 中使用 ! 前缀可以排除特定的类型声明包。

官方文档：https://www.typescriptlang.org/tsconfig/#typeRoots

5. paths 和 baseUrl：自定义模块解析路径

paths 和 baseUrl 选项允许你配置模块解析路径。通过自定义模块解析路径，可以跳过某些库的类型检查，或者为某些库提供替代的类型定义。baseUrl 用于指定解析非绝对模块名称的基本目录，而 paths 用于配置模块名称到实际文件路径的映射。

配置方法：

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "some-library": ["custom-types/some-library.d.ts"],
      "@third-party-library/*": ["src/lib/third-party-library/*"]
    }
  }
}
  

适用场景：

• 当你希望自定义模块解析路径时。
• 当你希望跳过某些库的类型检查时。
• 当你需要为某些库提供替代的类型定义时。

注意事项：

• paths 和 baseUrl 需要配合使用，否则可能会导致模块解析失败。
• 通过 paths 可以将模块名称映射到自定义的类型定义文件。

官方文档：https://www.typescriptlang.org/tsconfig/#paths

6. 自定义类型声明文件

如果第三方库的类型声明不准确或不完整，你可以创建自定义类型声明文件来覆盖原有的类型声明。例如，你可以在项目根目录下创建一个 types 文件夹，并在其中添加自定义类型声明文件。

示例：

// types/third-party-library/index.d.ts
declare module 'third-party-library' {
  // 自定义类型声明
  interface FormSelectItem extends FormItem {
    type: 'select';
    options: { value: string; label: string }[];
  }
}
  

然后在 tsconfig.json 文件中确保包含这个自定义类型声明目录：

{
  "compilerOptions": {
    // ...其他配置
    "typeRoots": ["node_modules/@types", "types"]
  }
}
  

适用场景：

• 第三方库的类型声明不准确或不完整。
• 你需要为某些库提供自定义的类型定义。

7. noCheck 选项 (实验性)

虽然 TypeScript 官方尚未正式支持 noCheck 选项，但社区中有一些关于添加该选项的讨论，该选项可以跳过指定文件或目录的类型检查。你可以通过以下方式实现类似的效果。

配置方法：

{
  "compilerOptions": {
    // 其他配置
  },
  "noCheck": [
    "path/to/your/library"
  ]
}
    

作用：

• 跳过指定文件或目录的类型检查。

适用场景：

• 当你希望跳过某些文件或目录的类型检查时。

注意事项：

• noCheck 选项目前尚未正式支持，因此需要谨慎使用。

参考链接：https://github.com/microsoft/TypeScript/issues/52325

在代码中使用 // @ts-nocheck 或 // @ts-ignore

虽然你提到不希望逐个文件添加 @ts-ignore 注释，但在某些情况下，这些注释仍然是可行的解决方案。它们可以用于临时跳过类型检查，或者在特定代码片段中禁用类型检查。

// @ts-nocheck：跳过整个文件的类型检查

在文件的顶部添加 // @ts-nocheck 注释，可以禁用整个文件的类型检查。

示例：

// @ts-nocheck
import someLibrary from 'some-library';

// 这里的代码不会进行类型检查
someLibrary.someMethod();
  

// @ts-ignore：跳过单行代码的类型检查

在需要忽略类型检查的行上方添加 // @ts-ignore 注释，可以禁用该行的类型检查。

示例：

// @ts-ignore
someLibrary.someMethod();
  

注意事项：

• 不推荐滥用这些注释，因为它们会完全跳过类型检查，可能导致隐藏的错误。
• 仅在你完全确定某段代码是安全的情况下使用。
• 如果需要在多个地方使用这些注释，可能需要考虑更改 tsconfig.json 文件的配置。

参考链接：https://stackoverflow.com/questions/53962788/how-to-ignore-some-files-when-running-type-checking-some-files-using-tsc

其他方法

使用 tsc --skipLibCheck 命令行参数

如果你不想修改 tsconfig.json 文件，可以在运行 tsc 命令时添加 --skipLibCheck 参数：

tsc --skipLibCheck
  

这种方法适合临时跳过类型检查，而不需要更改项目的配置文件。

使用 allowJs 和 checkJs 配置

如果你的项目中包含 JavaScript 文件，并且你不希望对这些文件进行类型检查，可以使用 allowJs 和 checkJs 配置。

配置方法：

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false
  }
}
  

适用场景：

• 你的项目中包含大量 JavaScript 文件，但你只想对 TypeScript 文件进行类型检查。
• 你正在逐步将项目从 JavaScript 迁移到 TypeScript。

总结

在 TypeScript 中跳过指定库的类型检查有多种方法，具体选择取决于你的需求和项目的实际情况。以下是一些建议：

• 全局跳过类型检查： 使用 skipLibCheck。
• 排除特定文件夹： 使用 exclude。
• 禁用类型获取： 使用 typeAcquisition.exclude。
• 自定义类型定义加载路径： 使用 typeRoots 和 types。
• 自定义模块解析路径： 使用 paths 和 baseUrl。
• 局部跳过类型检查： 使用 // @ts-ignore 或 // @ts-nocheck。
• 临时跳过类型检查： 使用 tsc --skipLibCheck 命令行参数。
• 跳过 JavaScript 文件的类型检查： 使用 allowJs 和 checkJs。
• 自定义类型定义： 创建 .d.ts 文件。

建议在开发阶段根据实际需求选择合适的方案，同时尽量保持类型系统的完整性，以便在生产环境中减少潜在问题。如果希望提高编译速度并减少第三方库的类型问题，skipLibCheck 是最简单和有效的解决方案。

参考资料：