TypeScript NoInfer 保持调用方的显式类型选择

泛型函数最容易出现一种“看起来更灵活，实际更难控制”的问题：第一个参数已经代表调用方选择的类型，后面的默认值或配置却继续参与推断，把 C 扩大成更宽的联合类型。TypeScript 5.4 提供的 NoInfer 适合处理这个边界：它仍然保留 T 的类型，但阻止被包裹位置贡献新的推断候选。

官方文档：https://www.typescriptlang.org/docs/handbook/utility-types.html

把“决定泛型是什么”和“检查参数是否符合泛型”拆开，正是 NoInfer 的价值。主参数负责选择，配置参数负责接受或拒绝这个选择。

多个参数一起推断时，类型为什么会被带偏

下面这个选择器希望由 items 决定 C，fallback 只能是同一组值：

function pickColor(items: C[], fallback?: C) {
  // 这里的 C 同时从两个参数寻找候选，调用方的 fallback 也会影响推断。
  return items.includes(fallback as C) ? fallback : items[0];
}

const color = pickColor(["red", "green"], "blue");
// 旧写法可能把 C 推成更宽的字符串联合，错误不一定落在 fallback 上。

问题不在数组和默认值不能同时出现，而在它们承担了同一个推断职责。对于 API 设计，通常应该让数据集合确定候选范围，再让默认值接受这个范围的检查。

用 NoInfer 把主推断源和约束源分开

将第二个参数包在 NoInfer 中，含义是“它必须符合已经推断出的 C，但不要用它反过来决定 C”：

function pickColor(items: C[], fallback?: NoInfer) {
  // items 决定候选集合，fallback 只负责接受已有集合中的值。
  return fallback !== undefined && items.includes(fallback) ? fallback : items[0];
}

pickColor(["red", "green"], "red");
pickColor(["red", "green"], "blue");
// 第二次调用应在 blue 处报错，而不是把 C 扩大后继续通过。

这不是把类型“锁死”，而是明确推断方向。若调用者确实需要另一种颜色，应改变 items 的类型或显式提供泛型参数，而不是让 fallback 偷偷扩大候选集。

对象配置和回调参数中的取舍

在配置对象里也可以采用同样的分层。下面的 schema 是主推断源，defaults 只是检查字段是否属于 schema：

type FieldMap = Record;

function createForm(
  schema: S,
  defaults?: Partial>,
) {
  // defaults 不再参与 S 的推断，但仍必须匹配 schema 的字段和值类型。
  return { schema, defaults };
}

createForm({ name: "text", age: 18 }, { age: 20 });
createForm({ name: "text" }, { missing: "x" });
// 第二次调用的字段不在 schema 中，应由类型系统直接提示。

回调场景要更谨慎：如果回调的参数本来就需要参与协变或逆变推断，过早使用 NoInfer 可能让 API 失去应有的灵活性。先画出类型来源，再决定哪些位置只是约束。

上线前的版本与回归检查

NoInfer 是 TypeScript 5.4 引入的全局工具类型。项目若仍由旧版本编译，不能只改源码；应先检查锁文件、编辑器语言服务和 CI 使用的 tsc 是否一致。回归时至少覆盖三种调用：合法默认值、完全不在候选范围内的值，以及通过显式泛型扩大主参数范围的调用。

type Allowed = "red" | "green";

function useMode(modes: C[], selected?: NoInfer) {
  // 运行时仍需处理空数组；NoInfer 只负责编译期的类型关系。
  return selected ?? modes[0];
}

useMode(["red", "green"], "red");
// @ts-expect-error：selected 不能绕过主参数给出的 Allowed 范围。
useMode(["red", "green"], "blue");

常见问题

NoInfer 会改变最终类型吗？

不会。它与内部的类型相同，主要变化是该位置不再提供推断候选。

用了 NoInfer 还需要运行时校验吗？

需要。它只约束编译期调用，外部 JSON、用户输入和 JavaScript 调用仍可能带来非法值。

为什么旧项目识别不了 NoInfer？

通常是 TypeScript 版本低于 5.4，或编辑器和 CI 使用了不同的编译器版本；先统一工具链再迁移。