TypeScript satisfies 运算符：与类型注解和 as 的区别

value satisfies Type 会在编译时检查 value 是否符合 Type，然后保持这个值自身更精确的类型不变。注解会用 Type 替换掉这个精确的类型；satisfies 只做校验，不会拓宽类型。

type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies Record<ColorName, Color>;

// Checked against the Record, yet every property keeps its own type:
console.log(palette.green.toUpperCase());      // #00FF00 (green: string)
console.log(palette.red.map((c) => c / 255));  // [ 1, 0, 0 ] (red: [number, number, number])

satisfies 照样会做检查：缺少某种颜色、拼错键名（比如 bleu），或者值写成了 true，都会在那一行报编译错误。它从 TypeScript 4.9 开始提供，和所有类型注解一样，会从生成的 JavaScript 中删除。

satisfies 解决的问题

使用类型注解时，变量的类型就是注解的类型。编译器会忘掉它在字面量中看到的信息。下面把同一个调色板改成用注解，这时 TypeScript 就不再知道 green 是字符串了：

// This does not compile: the annotation widens every property to Color.
type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette: Record<ColorName, Color> = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
};

console.log(palette.green.toUpperCase());

编译器报告：

index.ts(11,27): error TS2339: Property 'toUpperCase' does not exist on type 'Color'.
  Property 'toUpperCase' does not exist on type '[number, number, number]'.

在 TypeScript 4.9 之前，只能二选一：要么加注解，然后处处手动收窄类型（typeof palette.green === "string"）；要么不加注解，失去检查。satisfies 让你两者兼得。把 : Record<ColorName, Color> 改成写在右花括号后面的 satisfies Record<ColorName, Color>，代码就能运行了。

satisfies、类型注解与 as 对比

同一个设置对象的三种写法：

type Settings = {
  theme: "light" | "dark";
  fontSize: number;
  lang: string;
};

const annotated: Settings = { theme: "dark", fontSize: 14, lang: "en" };
const asserted = { theme: "dark", fontSize: 14 } as Settings; // lang is missing!
const satisfied = { theme: "dark", fontSize: 14, lang: "en" } satisfies Settings;

// annotated.theme: "light" | "dark"   (the annotation's type)
// satisfied.theme: "dark"             (what was actually written)
const isDark: "dark" = satisfied.theme; // fine; annotated.theme would be rejected

console.log(annotated.lang, asserted.lang, satisfied.lang); // en undefined en
console.log(isDark);                                         // dark

as 放过了缺失的 lang，于是 asserted.lang 在运行时是 undefined，而它的类型却声称是 string。从另外两行中去掉 lang，两者都会以 TS2741 失败：Property 'lang' is missing in type ...。

经验法则：希望变量拥有声明的类型时（会被重新赋值的值、公共 API），就用注解；想要检查、但值自身的类型更有用时，就用 satisfies。

捕获对象字面量中的错误

satisfies 会执行完整的可赋值性检查，包括多余属性检查，所以键名拼写错误会报错：

type Route = { path: string; method: "GET" | "POST" };

const home = { path: "/", metod: "GET" } satisfies Route;
// error TS2561: Object literal may only specify known properties, but 'metod' does not exist in type 'Route'. Did you mean to write 'method'?

这项检查还会像注解一样，为字面量提供上下文类型。这在两方面很重要。当目标类型需要字面量类型时，字符串字面量会保留为字面量类型：{ path: "/", method: "GET" } satisfies Route 中是 method: "GET"，而同一个对象如果不加注解，会被推断为 method: string。另外，回调函数的参数类型也会从目标类型推断出来：

type Handlers = {
  onSave: (doc: { id: number; title: string }) => string;
  onDelete: (id: number) => boolean;
};

const handlers = {
  onSave: (doc) => `saved #${doc.id}: ${doc.title}`, // doc is typed from Handlers
  onDelete: (id) => id > 0,
} satisfies Handlers;

console.log(handlers.onSave({ id: 7, title: "Notes" })); // saved #7: Notes
console.log(handlers.onDelete(-1));                      // false

Record 的键保持已知

一个常见用途是查找表。如果注解为 Record<string, T>，任何字符串都是合法的键，拼写错误也能通过编译，并在运行时返回 undefined。使用 satisfies 时，值仍会按 T 检查，但变量的类型恰好列出了你写的那些键：

type Endpoint = { url: string; timeoutMs: number };

const loose: Record<string, Endpoint> = {
  users: { url: "/api/users", timeoutMs: 3000 },
};

const endpoints = {
  users: { url: "/api/users", timeoutMs: 3000 },
  orders: { url: "/api/orders", timeoutMs: 8000 },
} satisfies Record<string, Endpoint>;

console.log(loose.userz?.url); // undefined: the typo compiles
console.log(endpoints.orders.timeoutMs); // 8000

type EndpointName = keyof typeof endpoints; // "users" | "orders"
const endpointName: EndpointName = "users";
console.log(endpoints[endpointName].url); // /api/users

// @ts-expect-error: TS2551 Property 'userz' does not exist on type ... Did you mean 'users'?
endpoints.userz;

keyof typeof endpoints 之所以有用，正是因为键被保留了下来。如果用注解，它就只是 string。

如果要求一组固定的键，就让值满足以联合类型为键的 Record：satisfies Record<"dev" | "prod", string> 会以 TS2741 报告缺少 prod，以 TS2353 报告未知的 staging。

as const satisfies

as const 和 satisfies 可以组合使用。as const 要写在前面：它让值变成深层 readonly 并带有字面量类型，然后 satisfies 再检查这个精确的值。

type Route = { path: string; method: "GET" | "POST"; auth: boolean };

const routes = [
  { path: "/", method: "GET", auth: false },
  { path: "/login", method: "POST", auth: false },
  { path: "/account", method: "GET", auth: true },
] as const satisfies readonly Route[];

type Path = (typeof routes)[number]["path"]; // "/" | "/login" | "/account"

function link(path: Path): string {
  return `<a href="${path}">`;
}

console.log(link("/account"));                           // <a href="/account">
console.log(routes.filter((r) => r.auth).map((r) => r.path)); // [ '/account' ]

每条路由都会按 Route 检查（写成 method: "PUT" 就会报错），同时字面量类型的元组依然可用，所以 Path 是真实路径组成的联合类型。目标类型要用 readonly Route[]（或 ReadonlyArray<Route>），因为 as const 数组是只读的。

配置对象

配置是 satisfies 大显身手的地方：结构必须正确，而其他地方的代码又需要精确的值。

type Env = "development" | "production";

type AppConfig = {
  port: number;
  logLevel: "debug" | "info" | "warn";
  features: Record<string, boolean>;
};

const configs = {
  development: { port: 3000, logLevel: "debug", features: { newCheckout: true } },
  production: { port: 8080, logLevel: "warn", features: { newCheckout: false } },
} satisfies Record<Env, AppConfig>;

function start(env: Env): string {
  const c = configs[env];
  return `${env}: port ${c.port}, log ${c.logLevel}, newCheckout=${c.features.newCheckout}`;
}

console.log(start("development")); // development: port 3000, log debug, newCheckout=true
console.log(start("production"));  // production: port 8080, log warn, newCheckout=false

忘了写 production 这一项、拼错 logLevel，或者写成 logLevel: "verbose"，编译器都会指出具体是哪一行。同样的模式也适用于 *.config.ts 文件：export default { ... } satisfies SomeConfig 会检查整个文件，同时导出的对象保留它的字面量值。

什么时候不该用 satisfies

• 变量会被重新赋值。 let cfg = { port: 3000 } satisfies { port: number | string } 让 cfg 的类型变成 { port: number }，所以之后的 cfg = { port: "80" } 会失败（TS2322）。打算修改的变量要用注解。
• 你本来就想要声明的类型。 对于函数返回值或者作为 API 一部分导出的常量，注解的类型就是契约，泄露精确的字面量类型可能让以后的修改变成破坏性变更。
• 值不是字面量。 satisfies 在对象和数组字面量上最能发挥作用。用在变量或函数调用结果上时，它只是普通的可赋值性检查，而注解本来就能做到这一点。