带泛型参数的命名空间出现循环引用错误的原因解析

先看触发错误的代码示例：

type Dict<T> = { [key:string]: T }

export namespace X {
    export type A<T> =
        | ['em', X.B<T>] // 触发循环引用错误
    export type B<T> = Dict<X.A<T>> // 触发循环引用错误
}

而以下两种修改方式都不会报错，我们来拆解背后的原因：

1. 移除命名空间前缀后不报错的原因 #

type Dict<T> = { [key:string]: T }

export namespace Y {
    export type A<T> =
        | ['em', B<T>] // 直接引用B<T>，无命名空间前缀
    export type B<T> = Dict<X.A<T>>
}

在命名空间内部引用同空间的泛型类型时，**使用非限定名称（省略命名空间前缀）**会让TypeScript延迟对该类型的完整解析，直到整个命名空间内的所有类型定义都进入初始化流程。这种延迟解析机制能让TypeScript正确处理互相依赖的循环泛型结构，不会触发循环引用错误。

而第一种报错的写法里，X.B<T>是完全限定的命名空间引用，TypeScript会在解析X.A<T>时立刻尝试解析X.B<T>的完整定义，此时X.B<T>又依赖未初始化完成的X.A<T>，导致类型检查器陷入无法完成的循环，触发错误。

2. 移除泛型参数后不报错的原因 #

type Dict<T> = { [key:string]: T }

export namespace Z {
    export type A =
        | ['em', Z.B]
    export type B = Dict<Z.A>
}

TypeScript原生支持非泛型类型的循环引用，即使使用完全限定的命名空间名称（如Z.B），类型检查器也能处理这种静态的循环结构——因为不需要处理泛型参数的动态实例化逻辑，类型定义是固定的，所以不会触发循环引用错误。

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