TypeScript .d.ts 导入导致全局类型失效：诊断和补救措施

问题背景

在 TypeScript 中，.d.ts 文件用于定义类型声明，允许我们使用外部库或模块而无需其源代码。通常，使用 declare 导入类型可以正常使用，特别是对于全局常量或简单类型定义。然而，当涉及到更复杂的场景时，例如在模块中使用这些类型，问题可能会出现。

根源探究

TypeScript 使用声明合并的概念，其中多个相同名称的声明会被合并为一个。当从 .d.ts 文件导入类型时，这些声明将与全局作用域中现有的声明合并。在某些情况下，这可能会导致意外的覆盖，从而导致全局类型失效。

情形 1：全局类型覆盖

如果 .d.ts 文件中声明的类型与现有全局类型具有相同的名称，则 .d.ts 文件中的声明将覆盖全局类型。这可能会导致在使用全局类型的代码中出现错误。

情形 2：模块作用域中的类型覆盖

当在模块中使用从 .d.ts 文件导入的类型时，模块作用域中的类型可能会覆盖全局类型。这与声明合并的规则有关，其中模块作用域中的声明优先于全局作用域中的声明。

解决之道

解决方法 1：显式导出模块类型

为了避免全局类型覆盖，可以在 .d.ts 文件中显式导出模块类型。这将创建一个新的模块作用域，其中包含从 .d.ts 文件导入的类型。

// my-module.d.ts
export declare module MyModule {
  export interface MyInterface {
    // ...
  }
}

在其他模块中，可以通过以下方式使用模块类型：

import { MyModule } from './my-module.d.ts';

const myInterface: MyModule.MyInterface = {
  // ...
};

解决方法 2：使用声明合并注释

另一种方法是使用声明合并注释 /// <reference> 来控制声明合并的行为。该注释允许您指定要合并的声明文件。

// my-module.d.ts
/// <reference path="./global-types.d.ts" />

export declare module MyModule {
  // ...
}

通过在 .d.ts 文件中包含此注释，您可以确保其声明与全局类型声明合并，从而避免覆盖。

解决方法 3：禁用声明合并

如果声明合并造成持续的问题，您可以禁用它。但是，不建议这样做，因为它会影响 TypeScript 的类型检查功能。

在 tsconfig.json 文件中添加以下设置：

{
  "compilerOptions": {
    "disableReferencedProjectLoad": true
  }
}

结论

在 TypeScript 中使用 .d.ts 文件导入类型时，了解声明合并的概念至关重要。通过采用适当的解决方法，例如显式导出模块类型、使用声明合并注释或禁用声明合并，您可以避免全局类型失效问题，确保您的 TypeScript 代码正常运行。