为JavaScript库编写.d.ts文件时，循环引用是否合规？

核心结论 #

纯类型层面的循环导入在.d.ts声明文件中是允许且安全的，TypeScript编译器在静态类型检查阶段能够正确解析这类循环引用，不会像JavaScript运行时那样出现未定义导出的问题。

为什么可行？ #

TypeScript的类型系统基于静态分析，编译时会整合所有模块的类型信息进行解析，而非像JS运行时那样按加载顺序执行代码。只要你的原JavaScript库本身不存在运行时循环依赖，声明文件里的类型循环引用只是描述代码的类型关系，不会影响实际运行逻辑。

需要避免的场景及问题示例 #

虽然纯类型循环导入没问题，但以下情况会引发问题，属于不良设计：

1. 在声明文件中混入可执行代码 #

.d.ts的核心作用是描述类型，若写入会被编译为运行时代码的逻辑，循环导入就会触发和JS运行时一样的问题：

• 文件a.d.ts（错误示例）：

import { B } from "./b";
export class A {
  static createB(): B {
    return {} as B;
  }
}
// 错误：在.d.ts中定义可执行的实例化代码
export const aInstance = new A();

• 文件b.d.ts（错误示例）：

import { A, aInstance } from "./a";
export interface B {
  getA(): A;
}
// 错误：引用声明文件中的可执行变量
export function getAFromB(b: B): A {
  return aInstance;
}

如果编译时误将这类.d.ts当作.ts处理（比如未正确配置include/exclude），运行时会出现aInstance未初始化的错误，因为循环加载时A类还未完全定义。

2. 复杂递归类型结合循环引用 #

当循环导入的类型结合条件类型、交叉类型等复杂逻辑时，可能导致TypeScript类型检查器无法解析，抛出递归过深的错误：

• 文件a.d.ts：

import { B } from "./b";
// 条件类型结合循环引用
export type A<T> = T extends 'b' ? B : string;

• 文件b.d.ts：

import { A } from "./a";
// 递归引用A类型
export type B = A<'a'> | number;

此时TypeScript会抛出Type instantiation is excessively deep and possibly infinite的编译错误，无法完成类型检查。

总结 #

• 仅包含类、接口、类型别名的纯类型循环导入，在.d.ts中是合理且安全的，不属于不良设计；
• 禁止在.d.ts中写入可执行代码，避免触发运行时循环依赖问题；
• 复杂类型逻辑应尽量避免循环导入，防止出现类型解析异常。

内容的提问来源于stack exchange，提问作者Yevgeniy P