TypeScript as const 与 satisfies 如何组合

在 TypeScript 配置对象里，如果你既想保留 "dark"、3000 这类字面量信息，又想让编译器检查键和值是否符合约束，可以把两者写在一起：

type AppConfig = {
  mode: "development" | "production";
  theme: "light" | "dark";
  timeoutMs: number;
  features: readonly ("search" | "export")[];
};

const config = {
  mode: "development",
  theme: "dark",
  timeoutMs: 3000,
  features: ["search", "export"],
} as const satisfies AppConfig;

// config.mode 保留为 "development"，config.features 是只读元组。
// satisfies 只检查结构兼容性，不会把 config 重新标成 AppConfig。

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

一句话记忆：as const 负责“把字面量推得更具体并加上只读属性”，satisfies 负责“检查它能不能满足某个类型”。前者影响推断结果，后者保留表达式自己的推断结果但增加编译期约束；两者都不会在浏览器运行时做校验。

先看 as const 到底改变了什么

普通对象字面量会根据上下文和可变性进行推断。例如下面的 theme 通常会被推成 string，而不是固定的 "dark"：

const normalConfig = {
  theme: "dark",
  retries: 3,
};

// theme 通常是 string，retries 通常是 number。
// 这适合需要后续修改的普通对象。
normalConfig.theme = "light";

const literalConfig = {
  theme: "dark",
  retries: 3,
} as const;

// as const 保留 "dark" 和 3，并把属性变成 readonly。
// literalConfig.theme = "light"; // 编译错误
// literalConfig.retries = 4;      // 编译错误

对数组来说，as const 会把可变数组推成只读元组。于是 ["search", "export"] 不再只是 string[]，而是保留元素位置和字面量的 readonly ["search", "export"]。

这里的只读是类型层面的限制，不等于 JavaScript 的深冻结。它不会自动调用 Object.freeze，也不会把运行时对象变成不可变数据。

单独使用 as const 为什么还不够

as const 能让值更具体，却不知道你的业务配置必须有哪些键。下面的拼写错误不会因为用了 as const 就自动被发现：

const configOnlyLiteral = {
  mod: "development",
  theme: "dark",
  timeoutMs: 3000,
} as const;

// as const 只处理这个表达式自身的推断。
// 它不会凭空知道业务上应该叫 mode，而不是 mod。
console.log(configOnlyLiteral.mod);

如果后续代码把这个对象传给要求 AppConfig 的函数，错误可能到使用点才出现。对于集中维护的路由表、主题表、功能开关和请求配置，最好在对象声明处就建立约束。

satisfies 如何检查形状又保留属性级推断

satisfies 的关键价值是：它会检查表达式是否兼容目标类型，但不会把表达式结果直接变成目标类型。下面同时演示漏键、错键和值类型错误：

type Theme = "light" | "dark";
type Feature = "search" | "export";

type AppConfigShape = {
  mode: "development" | "production";
  theme: Theme;
  timeoutMs: number;
  features: readonly Feature[];
};

const checkedConfig = {
  mode: "development",
  theme: "dark",
  timeoutMs: 3000,
  features: ["search", "export"],
} satisfies AppConfigShape;

// checkedConfig.theme 仍可按属性自身的推断使用。
const themeName = checkedConfig.theme.toUpperCase();

const badConfig = {
  mode: "development",
  theme: "dark",
  timeoutMs: "3000", // 类型错误：应为 number
  features: ["search"],
  them: "light", // 多余键错误：应检查拼写
} satisfies AppConfigShape;

对配置对象来说，satisfies 很适合放在声明处：目标类型描述允许的结构，表达式仍保留自己更具体的键和值信息。它不是运行时 schema，也不会替你检查来自接口、文件或用户输入的动态数据。

组合写法：as const satisfies

常量配置通常同时需要两个结果：不允许后续代码误改固定值，并且在配置变更时立即暴露键和值类型错误。组合写法就是：

type RouteConfig = {
  method: "GET" | "POST";
  cache: "no-store" | "force-cache";
  path: `/${string}`;
};

const userRoute = {
  method: "GET",
  cache: "no-store",
  path: "/users",
} as const satisfies RouteConfig;

// as const 保留 method、cache、path 的具体字面量并使其只读。
// satisfies 检查 path 以 / 开头、method 和 cache 属于允许集合。
function requestRoute(route: RouteConfig) {
  return `${route.method} ${route.path}`;
}

console.log(requestRoute(userRoute));

组合后的 userRoute.method 是 "GET"，不是宽泛的 "GET" | "POST"；但它仍然可以传给接收 RouteConfig 的函数。若把 path 改成 "users"，或者把 cache 写成未知字符串，错误会在配置声明处出现。

三个容易混淆的边界

1. as const 不是深冻结

字面量表达式中的嵌套属性会获得只读推断，但如果某个属性引用了外部可变对象，as const 不会把那个对象的内部状态一起冻结：

const featureList = ["search"];

const configWithReference = {
  features: featureList,
} as const;

// 外层 features 属性不能重新指向别的数组。
// configWithReference.features = []; // 编译错误

// 但被引用的原数组仍是 string[]，内部可以修改。
featureList.push("export");
console.log(configWithReference.features);

2. satisfies 不是运行时校验

下面的 JSON 来自网络时，TypeScript 编译器看不到它的真实运行时内容。即使把静态类型写成 satisfies，也不能阻止服务端返回缺少字段的数据；需要运行时校验时，应另选 schema 校验方案并处理失败分支。

3. 目标类型决定检查的边界

如果目标类型写得过宽，校验也会跟着变宽。比如 Record 只表达“键是字符串”，并不能约束每个业务字段。配置类型应明确列出必需键、联合值和可选项，才能让 satisfies 真正承担编辑期检查。

什么时候只用一种，什么时候组合

如果对象需要被后续逻辑修改，就不要为了“看起来更安全”强行使用 as const。如果你的目标是让一个变量对外暴露统一的宽类型，普通类型注解可能更合适；如果你要的是“声明处检查、使用处保留细节”，优先考虑 satisfies，再根据是否为常量决定要不要加 as const。

结论：把两种职责写在同一行

可以把 as const satisfies 当成静态配置的组合工具：as const 让字面量和只读信息留下来，satisfies 让配置对象在声明位置接受结构检查。它们只影响编译期类型系统，不负责运行时冻结和外部数据校验。

相关问题

as const satisfies T 和 : T 有什么区别？

: T 会让变量按 T 的视角使用；satisfies T 检查兼容性但保留表达式自身的更具体推断。常量配置需要精确字面量时，再加上 as const。

as const 能代替 Object.freeze 吗？

不能。它是编译期断言，不会在运行时冻结对象；而且外部引用对象的内部状态仍可能被修改。

satisfies 能校验接口返回的 JSON 吗？

不能单独完成。接口响应在运行时才出现，需要运行时 schema 校验或手动检查，并在失败时走明确的错误处理路径。