字面量类型

字面量类型（literal type） 只包含一个精确值，例如字符串值"queued"、数字值404、大整数值10n，或者布尔值true。 string表示所有字符串，而"queued"只表示这一个字符串。 这种精度让编译器判断一个值是否真的属于某个有限协议，而不只是拥有相同的原始类型。

实际代码通常把多个字面量放进 联合类型（union type） ，例如"GET" | "POST"。 这个类型表示一个封闭集合：值可以是"GET"，也可以是"POST"，但不能是任意其他字符串。 字符串字面量最常见，数字、bigint和布尔字面量也遵循相同的可赋值规则。

字面量类型解决的是“这个位置允许哪些精确值”，而不是“这个位置存放哪种原始数据”。 当业务规则由少量稳定选项组成时，这个区别很有用，例如任务状态、命令名称、日志级别、重试次数或响应标签。 拼错的状态可以在编译阶段被拒绝，编辑器也能根据联合给出补全。

字面量字段还可以连接一个对象的标签与载荷。 如果status: "complete"的成员一定带有url，而status: "failed"的成员一定带有message，检查status后就能安全访问对应字段。 这种结构叫作 可辨识联合（discriminated union） 。

字面量类型不是输入验证器，也不会把类型信息带进生成的JavaScript。 网络响应、JSON、环境变量和普通JavaScript调用方仍可能提供集合外的值。 这些值应先以unknown或宽泛的运行时类型进入边界，通过真实检查后才能获得字面量联合类型。

如果允许值本来就是开放的，例如用户名或任意URL，就应继续使用string。 把每个示例值都做成联合会把数据误写成封闭协议，并让正常扩展变成无意义的类型改动。 字面量类型适合有限、可枚举而且由程序维护的选择。

类型检查器把类型看作一组可能值。 字面量类型对应单元素集合，联合操作符|则合并多个集合。 因此，type Speed = "standard" | "express"恰好包含两个字符串值，并且仍然可以赋给接受任意string的位置。

反方向不成立。 一个普通string可能在运行时是"overnight"，所以不能赋给只接受Speed的参数。 赋值是否有效取决于源类型的每个可能值能否落在目标集合中，而不是当前运行时值碰巧看起来正确。

值、类型与可赋值性

表达式"express"既产生JavaScript字符串值，也向检查器提供精确的字面量信息。 类型注解const speed: Speed = "express"检查初始化值属于联合，并把变量的公开契约固定为Speed。 以后修改联合时，所有依赖该契约的位置会一起重新检查。

字面量联合没有自己的运行时容器。 它不会像普通enum那样生成可读取的对象，也不能用Object.values(Speed)枚举，因为Speed只存在于类型位置。 运行时也需要选项列表时，可以从一个as const元组派生联合，让值与类型共享一份来源。

布尔类型可以理解为true | false。 单独的true类型适合表达已经满足的条件或泛型分支结果，但普通功能开关通常仍应使用boolean。 数字字面量适合少量有领域含义的代码或档位，不适合描述任意整数范围。

null和undefined也各自只有一个运行时值，并且经常出现在联合中。 它们主要用于缺失值建模；本文重点讨论可由字符串、数字、bigint和布尔表达式产生并发生拓宽的字面量。

推断与字面量拓宽

类型推断（type inference） 会从初始化表达式、调用参数和周围的预期类型收集信息。 检查器需要在精度与后续可变性之间取舍。 一个不会重新赋值的原始const可以保持精确，而let通常要允许同类的其他值。

例如，const mode = "dark"通常得到类型"dark"，因为变量绑定不能换成别的值。 let mode = "dark"通常得到string，否则下一行合法的mode = "light"就会被初始化值意外禁止。 从精确字面量移动到更宽原始类型的过程叫作 字面量拓宽（literal widening） 。

const只固定变量绑定，不会让对象属性自动只读。 在const request = { method: "GET" }中，之后仍能执行request.method = "POST"，所以method通常推断为string。 同理，普通数组字面量const methods = ["GET", "POST"]通常得到string[]，而不是固定长度元组。

显式上下文可以避免过早拓宽。 如果变量声明为const method: "GET" | "POST" = "GET"，或者对象传给已声明该联合的参数，初始化值会按这个预期类型检查。 上下文给出允许集合，表达式则必须落在集合内。

下面的对照描述常见声明产生的静态结果。

as const保留字面量信息

as const断言（const assertion） 要求检查器不要拓宽字面量表达式。 对象字面量的属性会成为readonly，数组字面量会成为只读元组，其中每个元素保留自己的字面量类型。 它适合选项表、路由表、动作定义和其他由源码维护的常量数据。

as const是静态指令，不是运行时冻结操作。 生成的JavaScript中没有这段类型语法，引用到的已有可变对象也不会被递归复制或冻结。 如果运行时调用方可能修改对象，需要另外设计所有权或使用真实的冻结操作。

as const还可能得到比API契约更窄的类型。 如果对象之后确实要在多个允许值之间变化，应该给它一个可变的联合注解，而不是先做常量断言再到处强制转换。 精确并不总是更好；精度必须符合值的生命周期。

satisfies检查而不替换表达式类型

satisfies操作符检查左侧表达式可以赋给右侧类型，同时保留左侧有用的推断细节。 它很适合检查配置对象是否覆盖规定的键、属性值是否属于联合，同时让每个已写入的值继续保持具体类型。 与直接注解相比，它通常不会把整个变量的可见类型替换成目标类型。

satisfies不会让对象自动只读，也不会验证运行时数据。 需要只读字面量时可以在合适位置结合as const；需要验证JSON时必须执行值检查。 它们解决的是不同问题，不能因为语法都出现在表达式末尾就互换。

比较会触发收窄

当联合值与某个字面量比较时， 控制流收窄（control-flow narrowing） 会在对应分支移除不可能的成员。 对于Speed，条件speed === "express"让真分支中的值精确为"express"，假分支则只剩"standard"。 这是普通JavaScript比较与静态联合信息共同产生的结果。

可辨识联合把这个规则扩展到整个对象。 联合的每个成员共享一个属性名，但给它不同的字面量值；检查该属性后，TypeScript会同时收窄其他字段。 标签必须真正区分各成员，不能在每个成员上都写成相同的宽泛string。

switch很适合处理封闭联合，但只有写出穷尽性检查，新增成员时才一定会暴露遗漏。 所有已知分支返回后，剩余值应为never；把它传给只接受never的辅助函数即可让编译器验证这一点。 一个什么都接受的default分支反而会隐藏新成员。

下面四个示例从单个联合开始，接着建立值与类型的单一来源，再把字面量用作对象标签，最后比较satisfies与直接注解。 每段代码都可以单独运行，不依赖网络或其他文件。

限制函数输入

ShippingSpeed把配送速度限制为两个允许值。 函数内部的比较也会把两个分支分别收窄为对应字面量。

注解把函数边界写成封闭契约，调用方仍然直接传普通字符串字面量。 如果传入"overnight"，错误会出现在调用位置，而不是等到函数内部落入意外分支。

运行输出只包含普通字符串。 ShippingSpeed在编译后被擦除，所以这个精确类型没有额外的运行时对象或转换成本。

从运行时元组派生联合

当程序既要在运行时枚举选项，又要在类型系统中复用它们时，先写值列表。 typeof CHANNELS[number]取得只读元组所有数字索引位置的元素类型，因此生成"email" | "sms" | "push"。

const CHANNELS = ["email", "sms", "push"] as const;
type Channel = (typeof CHANNELS)[number];

function isChannel(value: string): value is Channel {
  return CHANNELS.some((channel) => channel === value);
}

function subscribe(input: string): string {
  if (!isChannel(input)) {
    return `unsupported: ${input}`;
  }

  return `subscribed: ${input}`;
}

console.log(CHANNELS.join(", "));
console.log(subscribe("push"));
console.log(subscribe("fax"));

email, sms, push
subscribed: push
unsupported: fax

这里的元组是运行时事实，Channel是从它派生的静态事实。 增加一种渠道时，只修改CHANNELS就会同时更新迭代结果、守卫和联合类型。

isChannel执行真实比较，所以它可以把外部字符串收窄为Channel。 类型谓词value is Channel描述函数成功返回时已经证明的事实；如果实现与谓词不一致，检查器不会替你发现这个谎言。

这个模式适合由当前程序拥有的短列表。 如果允许值由服务器部署、插件或数据库动态决定，就不能把构建时元组假装成完整的运行时来源。

用字面量标签关联状态与数据

每个UploadState成员都有status，但其余字段取决于这个标签。 switch检查标签后，每个分支只能访问该状态真正拥有的载荷。

type UploadState =
  | { status: "queued"; file: string }
  | { status: "uploading"; file: string; percent: number }
  | { status: "complete"; file: string; url: string }
  | { status: "failed"; file: string; message: string };

function assertNever(value: never): never {
  throw new Error(`Unexpected state: ${JSON.stringify(value)}`);
}

function describe(state: UploadState): string {
  switch (state.status) {
    case "queued":
      return `${state.file}: waiting`;
    case "uploading":
      return `${state.file}: ${state.percent}%`;
    case "complete":
      return `${state.file}: ${state.url}`;
    case "failed":
      return `${state.file}: ${state.message}`;
    default:
      return assertNever(state);
  }
}

const states: UploadState[] = [
  { status: "queued", file: "avatar.png" },
  { status: "uploading", file: "report.pdf", percent: 60 },
  { status: "complete", file: "map.svg", url: "/files/map.svg" },
];

for (const state of states) console.log(describe(state));

avatar.png: waiting
report.pdf: 60%
map.svg: /files/map.svg

assertNever的主要作用发生在类型检查阶段。 如果给UploadState添加"paused"成员却不添加对应分支，state在default中就不再是never，编译会失败。

辅助函数中的throw仍有运行时价值。 未经验证的JavaScript或错误断言可能绕过静态类型，运行时遇到未知标签时不会静默产生看似正常的文本。

不要把几个可选字段塞进一个带宽泛status: string的接口来替代这个联合。 那种结构会允许status: "complete"却没有url的非法组合，也无法让控制流建立字段关系。

用satisfies检查配置形状

配置必须恰好包含两个环境，每个重试次数也必须属于规定联合。 satisfies执行这些检查，同时让两个已写入的重试值分别保留为0和3。

type Environment = "development" | "production";
type ServiceConfig = {
  endpoint: string;
  retry: 0 | 1 | 2 | 3;
};

const services = {
  development: { endpoint: "http://localhost:3000", retry: 0 },
  production: { endpoint: "https://api.example.com", retry: 3 },
} satisfies Record<Environment, ServiceConfig>;

function retryLabel(count: 0 | 3): string {
  return count === 0 ? "no retries" : "three retries";
}

console.log(`${services.development.endpoint}: ${retryLabel(services.development.retry)}`);
console.log(`${services.production.endpoint}: ${retryLabel(services.production.retry)}`);

http://localhost:3000: no retries
https://api.example.com: three retries

如果键名拼错或写入retry: 5，错误会落在配置对象上。 如果直接把变量注解为Record<Environment, ServiceConfig>，读取具体属性时看到的重试类型会是完整联合0 | 1 | 2 | 3。

这里没有使用as const，所以endpoint等可变属性并未整体变成只读。 该例需要的是形状校验与字面量精度，不是假定整个配置永远不能修改。

satisfies右侧同样会在输出JavaScript时消失。 如果这份配置来自文件而不是源码对象，仍要解析并验证实际内容。

修复方法： 如果对象要修改，就给属性写联合注解；如果它是常量数据，就使用as const。 只需要检查结构但不想替换推断类型时，使用satisfies。

修复方法： 在信任边界执行成员检查，并根据真实所有权决定是否冻结对象。 类型精度、运行时有效性和可变性是三项不同的保证。

修复方法： 如果值来自受控源码，修正声明位置的推断或注解；如果值来自外部，先验证再返回联合。 不要把断言当作从宽类型到窄类型的通用转换函数。

修复方法： 先决定API是封闭集合还是开放字符串。 确实允许任意扩展值时，运行时验证、编辑器补全和兼容策略应按开放协议设计，不能继续声称联合会拒绝未知值。

修复方法： 让已知分支结束控制流，再把剩余值交给assertNever。 同时保留运行时抛错，以便发现从未验证的调用路径。

修复方法： 对开放数值使用number，并在运行时检查有限性、整数性和范围。 只有当0 | 1 | 2 | 3本身就是领域选项时，才把这些数字写成字面量联合。

• TypeScript手册：字面量类型
• TypeScript手册：可辨识联合与穷尽性检查
• TypeScript 3.4发布说明：const断言
• TypeScript 4.9发布说明：satisfies操作符
• TypeScript 5.0发布说明：const类型参数