TypeScript satisfies 和类型断言有什么区别

TypeScript 里的 satisfies 和 as 都能出现在类型相关代码中，但职责完全不同：satisfies 是“请检查这个值是否符合契约，同时保留它原本的推断结果”；类型断言是“我已经知道这个值是什么类型，请按我说的类型继续检查”。前者偏向建立配置契约，后者偏向表达调用者掌握的额外事实。

先看结果：satisfies 保留推断，断言改变检查视角

假设应用需要一组固定颜色。直接写对象时，TypeScript 能推断出具体属性，但不会自动检查键集合是否完整；给对象加宽泛类型注解能检查键和值，却会让属性读取变成联合类型。satisfies 正好把这两件事拆开：验证契约，保留表达式自身的类型。

type ColorName = "primary" | "danger";
type ColorValue = string | [number, number, number];

const palette = {
  primary: "#2563eb",
  danger: [220, 38, 38],
} satisfies Record;

// 属性仍保留具体推断，因此这里可以直接调用字符串方法
const primaryHex = palette.primary.toUpperCase();
// 元组仍然是可索引的具体值
const red = palette.danger[0];

如果把同一个对象写成 const palette: Record，键错误仍会被发现，但读取 palette.primary 时通常只能得到 string | [number, number, number]。而 as Record 更像一次“相信我”的声明，它不会替你证明对象真的满足契约。

什么时候应该用 satisfies

它最适合源码里由开发者维护、需要固定键和值约束的对象：路由表、主题配置、权限映射、组件参数表和本地化资源都属于这一类。典型目标是既防止拼写错误，又让调用点获得精确推断。

type RouteName = "home" | "settings";
type RouteConfig = {
  path: `/${string}`;
  auth: boolean;
};

const routes = {
  home: { path: "/", auth: false },
  settings: { path: "/settings", auth: true },
} satisfies Record;

// 这里得到的是字面量对象的属性，而不是被统一扩宽后的 RouteConfig
const settingsPath = routes.settings.path;

当键集合必须完整时，Record 会检查少键和多键；当只关心所有值的形状时，可以把键写成 string。注意，satisfies 仍然只是编译期约束，不能把 JSON、接口响应或用户输入变成可信数据。

什么时候只能把类型断言当作已知事实

类型断言适合调用者确实掌握、而类型系统无法从当前代码推导出的事实。例如 DOM 查询返回的是通用 HTMLElement | null，但页面约定某个 id 一定对应画布。断言不会创建画布，也不会替你检查元素是否存在，因此生产代码仍应处理空值。

const canvas = document.getElementById("preview") as HTMLCanvasElement | null;

if (canvas) {
  // 运行时的 if 负责处理不存在元素，断言只补充元素类型信息
  const context = canvas.getContext("2d");
  context?.clearRect(0, 0, canvas.width, canvas.height);
}

外部 JSON 则不应该因为“接口文档写着这样”就直接断言。更稳妥的边界是先把结果当成 unknown，经过字段检查或运行时 schema 校验后，再让后续函数接收明确类型。as any as T 只能绕开编译器的重叠检查，不会增加任何运行时保护。

两种语法怎么选：一张表记住边界

一个实用判断是：你是在要求编译器“帮我检查这个值”，还是在告诉编译器“我已经在别处检查过了”？前者用 satisfies，后者才考虑断言；如果两件事都没有发生，就不要用语法把不确定性藏起来。

常见问题

satisfies 会在运行时校验对象吗？

不会。它和类型注解一样只参与 TypeScript 编译期检查，生成的 JavaScript 不会留下校验逻辑。

satisfies 和 as const 能一起用吗？

可以。常见写法是先用 as const 保留只读字面量，再用 satisfies 检查整体契约；两者解决的是“推断精度”和“契约校验”两个不同问题。

为什么断言后仍然可能报错？

断言只改变表达式在类型检查中的视角，不能修复真实值、缺失字段或空值。后续操作若违反断言后的类型假设，问题仍会在运行时暴露。