TypeScript satisfies怎么配置或排查

很多人第一次写 satisfies，会先去找 tsconfig.json 里的开关。实际上它不是一个需要单独启用的编译选项，而是 TypeScript 4.9 加入的类型运算符：检查表达式是否符合目标类型，同时尽量保留表达式本身的具体推断。如果编辑器报“无法解析”或构建时突然出现语法错误，优先检查项目真正使用的 TypeScript 版本和构建链解析器。

官方地址：https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html

先确认版本：它不是 tsconfig 里的配置项

satisfies 的最低语言支持来自 TypeScript 4.9。项目里即使安装了新版本，也可能由编辑器工作区、Monorepo 根目录或构建插件调用另一份旧编译器。可以先查看实际解析到的版本：

# 查看当前工作目录真正调用的 TypeScript 版本
npx tsc --version

# 只做类型检查，不生成文件，便于隔离解析和类型错误
npx tsc --noEmit

如果 tsc 能识别而打包器仍报语法错误，问题通常不在类型规则，而在 Babel、旧版 loader 或自定义解析器没有把该语法交给 TypeScript 处理。先让编辑器、命令行和构建脚本统一到同一份依赖，再改配置。

satisfies 的正确用法：约束配置，保留属性推断

下面的例子把配置键限制为固定集合，并要求每个值是字符串或 RGB 元组。拼写错误和元组长度错误都会在声明位置被发现，但 palette.green 仍可按字符串使用。

type ColorName = "red" | "green" | "blue";
type RGB = [red: number, green: number, blue: number];

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255]
  // 这里会保留每个属性的具体类型，同时检查整体是否满足约束
} satisfies Record;

// green 仍被推断为字符串，因此可以直接调用字符串方法
const normalized = palette.green.toUpperCase();

这里的关键不是“把对象强行变成 Record”，而是给对象增加一条可检查的边界。缺少 blue、多出不允许的键，或把 RGB 写成两个数字，都会在这条边界上暴露。

三种写法怎么选：注解、断言和 satisfies 不等价

如果后续代码只需要抽象接口，类型注解更直白；如果数据来自可信边界且确实需要转换视角，才考虑断言。对“既要检查键和值，又要继续享受具体属性推断”的配置，satisfies 更合适。需要保留数组或对象的字面量时，可以把 as const 放在表达式内部，再让外层的 satisfies 做兼容性检查。

报错时按位置排查，不要先乱加 as

可以把现象分成四类：整行出现未知语法，先查 TypeScript 或构建解析器版本；红线落在键名上，检查联合类型是否遗漏该键；红线落在值上，检查字符串、数字和元组结构；代码能通过但后续推断不符合预期，再比较注解与 satisfies 的结果。

type Feature = "search" | "export";
type FeatureConfig = Record;

const features = {
  search: { enabled: true },
  export: { enabled: false }
  // 键名或 enabled 的类型错误，应在这里修复，而不是先追加 as
} satisfies FeatureConfig;

// 通过 tsc 后再使用具体属性，避免把构建问题误判成运行时问题
if (features.search.enabled) {
  console.log("search enabled");
}

最小检查只保留一份类型定义、一个对象和一条使用语句。这样能快速判断是语言版本、目标类型写错，还是编辑器语言服务缓存没有更新。确认命令行通过后，再重启编辑器或清理构建缓存；不要用断言把错误压掉。

常见问题

satisfies 需要在 tsconfig.json 中开启吗？

不需要独立开关。安装并实际使用支持它的 TypeScript 编译器即可，目标配置主要影响项目其他语法和库类型。

为什么 satisfies 通过后属性仍然是联合类型？

它保留表达式的真实推断，不会替你做运行时判断。如果值本身确实是联合类型，后续仍需按 TypeScript 规则收窄。

报错是旧浏览器不支持吗？

这是编译期语法，不是浏览器运行时 API。浏览器通常看不到它，因为编译输出会移除类型信息；应先查编译器和构建解析链。