TypeScript函数重载：如何禁止传入单个any类型参数？

你的问题核心在于：原有的重载允许f(undefined)，但当传入any类型的单个参数时，TypeScript会因为any可以兼容undefined而错误匹配第一个重载，导致不符合“其余情况必须传两个参数”的需求。下面是具体的解决方案：

步骤1：定义辅助类型排除any #

首先我们需要一个类型工具，用来区分真正的undefined和可以兼容undefined的any类型：

type ExcludeAny<T> = T extends any ? (any extends T ? never : T) : never;

这个类型的逻辑是：如果传入的类型T是any，则返回never（因为any extends T当T是any时成立）；否则返回原类型T。这样就能把any从允许的参数类型中排除出去。

步骤2：修改函数重载 #

用上面的辅助类型替换第一个重载的undefined类型，同时保留第二个重载的定义：

type ExcludeAny<T> = T extends any ? (any extends T ? never : T) : never;

// 第一个重载：仅允许真正的undefined，排除any
function f(key: ExcludeAny<undefined>);
// 第二个重载：必须传入两个参数，参数类型保持原需求
function f(key: string | undefined, value: object | undefined);
// 函数实现
function f(key?: string | undefined, value?: object | undefined) {
  // 这里写你的函数逻辑
  console.log(key, value);
}

测试验证 #

现在我们来验证各种调用场景是否符合预期：

允许的调用 #

• 显式传入单个undefined：f(undefined) ✅
• 传入类型为undefined的变量：

  const val: undefined = undefined;
  f(val); // ✅
  

• 传入两个参数的各种合法组合：

  f("hello", { name: "test" }); // ✅
  f(undefined, { age: 20 }); // ✅
  f("world", undefined); // ✅
  

禁止的调用 #

• 传入单个any类型参数：

  const anyVal: any = 123;
  f(anyVal); // ❌ 报错：缺少第二个参数，且第一个参数类型不匹配
  

• 传入单个非undefined的参数：

  f("only-key"); // ❌ 报错：无匹配的重载
  

原理说明 #

通过ExcludeAny<undefined>，我们把第一个重载的参数类型限制为仅能被真正的undefined类型匹配，而any类型会被转换成never，无法匹配第一个重载。此时单个any参数的调用会尝试匹配第二个重载，但第二个重载要求两个参数，因此会触发编译错误，完美符合你的需求。

内容的提问来源于stack exchange，提问作者Qwertiy