Skip to content

幻影类型(Phantom Type)

一句话解释

幻影类型是未使用的类型参数,添加编译时区分而无运行时开销。

用大白话说

幻影类型是永远不出现在实际数据中的泛型类型参数——它仅存在于类型级以创建区分。例如,type Meter<T> = number——T 不出现在值中(始终是数字),但不同的 T 值创建不同类型:Meter<"distance"> vs Meter<"time">。这让你在类型级用元数据标记值:

  • 状态机(Idle vs Running 状态)
  • 单位(米 vs 秒)
  • 能力(已授权 vs 未授权)
  • 计算阶段无运行时开销——幻影参数被擦除。纯粹是编译时安全机制。

示例

typescript
// Phantom type — T is never used in the value
type Tagged<T extends string> = { readonly _tag: T; value: number };

type Meters = Tagged<"distance">;
type Seconds = Tagged<"time">;

function speed(d: Meters, t: Seconds): number {
  return d.value / t.value;
}

const dist: Meters = { _tag: "distance", value: 100 };
const time: Seconds = { _tag: "time", value: 10 };

console.log(speed(dist, time)); // 10
// speed(time, dist); // Error! Wrong types

Meters 和 Seconds 运行时都是 { value: number },但 _tag 幻影在编译时区分它们。不能在 speed() 中交换。

常见混淆

  • 容易混淆的对象: 品牌类型

    关键区别: 品牌类型向值添加幻影属性(与 { __brand: 'X' } 交集)。幻影类型使用根本不出现在值中的类型参数。两者都创建编译时区分;品牌类型用属性,幻影类型用未使用的类型参数。

相关术语

相关资源

相关课程

解读错误信息

用大白话解释常见错误——什么意思、为什么发生、如何修复。

查看错误

← 返回术语表