TypeScript 字面量类型与 as const 用法详解

字面量类型是只有一个值的类型："up" 这个类型唯一的成员是字符串 "up"，404 这个类型唯一的成员是数字 404。单独使用时它们用处不大，但组合成联合类型后，就能得到一个只接受一组固定值、其他值一律拒绝的变量。

type Direction = "up" | "down" | "left" | "right";

function move(dir: Direction, steps: number) {
  console.log(`moving ${dir} by ${steps}`);
}

move("up", 3);
move("left", 1);

// @ts-expect-error: Argument of type '"north"' is not assignable to parameter of type 'Direction'.
move("north", 1);

如果没有 @ts-expect-error 注释，最后一次调用会产生编译错误（TS2345）。加上注释后，程序可以编译，这次调用照样会运行并打印 moving north by 1：字面量类型只存在于编译器中，运行时这个值就是一个普通字符串。

字符串、数字和布尔字面量

任何字符串、数字、bigint 或布尔值都可以写成类型，编译器随后只接受这个确切的值。

let method: "GET" = "GET";
let code: 404 = 404;
let ok: true = true;
let big: 10n = 10n;

type Port = 80 | 443 | 8080;
const port: Port = 443;

boolean 本身就是联合类型 true | false，所以用 if (flag) 收窄一个 boolean 之后，else 分支里剩下的就是 false。

字面量联合类型

最常见的用法是用联合类型列出所有允许的值。在函数内部，编译器会随着你的检查收窄联合类型，所以每个分支都确切知道自己拿到的是哪个值。

type Size = "sm" | "md" | "lg";

function padding(size: Size): number {
  if (size === "sm") return 4;
  if (size === "md") return 8;
  return 16; // size is "lg" here
}

const sizes: Size[] = ["sm", "md", "lg"];
console.log(sizes.map(padding)); // [ 4, 8, 16 ]

字符串字面量联合类型是 TypeScript 中替代枚举的常用做法。它没有任何运行时开销，值就是普通字符串，可以直接打印、通过 JSON 传输，而写错一个字母就是编译错误。两者的取舍详见枚举。

类型拓宽：let 与 const

TypeScript 根据字面量推断类型时，会看这个值能不能改变。const 变量永远不能被重新赋值，所以保留字面量类型；let 变量可以，所以它的类型会被拓宽为通用类型。

const a = "hello"; // type: "hello"
let b = "hello";   // type: string
b = "bye";         // fine, b is a string

const n = 42;      // type: 42
let m = 42;        // type: number

let c = a;         // type: string (copying a literal into a let widens it)

console.log(a, b, n, m, c); // hello bye 42 42 hello

在编辑器中把鼠标悬停在每个名称上，就能看到推断出的类型。如果你想要一个只能保存特定值的 let，就给它加上标注：let mode: "light" | "dark" = "light"。

为什么对象属性会被拓宽

对象字面量的属性是可变的，所以即使对象存放在 const 中，属性也会被拓宽。这是最常见的意外碰上字面量类型的情形：

// This does not compile: req.method is string, not "GET" | "POST"
function send(url: string, method: "GET" | "POST") {
  console.log(method, url);
}

const req = { url: "/users", method: "GET" };
send(req.url, req.method);

编译器报告：

index.ts(7,15): error TS2345: Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'.

req 被推断为 { url: string; method: string }，因为之后的代码可能会执行 req.method = "DELETE"。有三种修复方法：

type Method = "GET" | "POST";

function send(url: string, method: Method) {
  console.log(method, url);
}

// 1. Annotate the object (or the property)
const r1: { url: string; method: Method } = { url: "/users", method: "GET" };

// 2. as const on the whole object: every property becomes readonly and literal
const r2 = { url: "/posts", method: "POST" } as const;

// 3. as const on one property only
const r3 = { url: "/tags", method: "GET" as const };

send(r1.url, r1.method);
send(r2.url, r2.method);
send(r3.url, r3.method);

第四种办法是 satisfies，它会按某个类型检查对象，同时保留属性的字面量类型。

as const

as const 是 const 断言。把它写在表达式后面，编译器就会推断出尽可能窄的类型：

• 字符串、数字和布尔值保留字面量类型
• 对象属性变为 readonly
• 数组字面量变为长度固定的 readonly 元组

const config = {
  env: "production",
  retries: 3,
  hosts: ["a.example.com", "b.example.com"],
} as const;
// type: { readonly env: "production"; readonly retries: 3;
//         readonly hosts: readonly ["a.example.com", "b.example.com"] }

// @ts-expect-error: Cannot assign to 'env' because it is a read-only property.
config.env = "staging";

const point = [3, 4] as const; // type: readonly [3, 4]
const [x, y] = point;
console.log(config.retries, x + y); // 3 7

这个断言只在编译时起作用。生成的 JavaScript 就是去掉 as const 的同一个对象字面量，所以运行时没有什么能阻止其他代码修改它。如果需要运行时的保证，再调用一次 Object.freeze。

从 as const 数组得到联合类型

一个常见的模式是把允许的值放在一个数组里（运行时可以遍历它），再从中推导出联合类型。(typeof arr)[number] 的意思是“arr 中任意一个元素的类型”。

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

for (const input of ["editor", "owner"]) {
  console.log(input, isRole(input)); // editor true, then owner false
}

不加 as const 的话，ROLES 会是 string[]，Role 也就只是普通的 string。isRole 中需要转换成 readonly string[]，是因为字面量元组上的 includes 只接受这些字面量，而这个函数的目的恰恰是检查一个可能不在其中的字符串。同样的模式也适用于键值映射：const Status = { Active: "active", Banned: "banned" } as const，然后 type Status = (typeof Status)[keyof typeof Status]。

const 类型参数

泛型函数通常会拓宽你传入的字面量。从 TypeScript 5.0 开始，你可以把类型参数标记为 const，编译器就会像实参带了 as const 一样推断它，而不需要调用方自己写。

function plain<T>(value: T) {
  return value;
}

function exact<const T>(value: T) {
  return value;
}

const a = plain({ kind: "circle", sizes: [1, 2] });
// type: { kind: string; sizes: number[] }

const b = exact({ kind: "circle", sizes: [1, 2] });
// type: { readonly kind: "circle"; readonly sizes: readonly [1, 2] }

console.log(a.kind === b.kind); // true

这主要是给库作者用的工具：路由定义、构建器和 schema 辅助函数都用它，让调用方从普通字面量中得到精确的类型。

const 的几种含义

关键字 const 在 TypeScript 代码中会出现在四个不同的地方：

它们都不会在运行时冻结对象。const obj = { a: 1 } 仍然允许 obj.a = 2，只有重新给 obj 本身赋值才会报错。