在 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文件的配置。
其他方法
使用 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 是最简单和有效的解决方案。
参考资料：
Last updated January 6, 2025