TypeScript函数重载报错：参数为Point|undefined时无匹配重载

问题场景 #

当定义函数重载，让参数为Point时返回Point，参数为undefined时返回undefined，但传入Point | undefined类型的参数时，会触发编译错误。

示例代码 #

type Point = { x: number; y: number }

function symetry(point : Point) : Point;
function symetry(point : undefined ) : undefined;
function symetry(point : Point | undefined) : Point | undefined {
    if(!point) return undefined;
    return {
        x : -point.x,
        y : -point.y
    }
}

const p1 : Point = symetry({x: 10, y:-4});
const someFunc = (v : number): Point | undefined =>{
    if(v%2 === 0) return undefined;
    return { x:v,y:v}
}

const p2 = symetry(someFunc(0));
const p3 = symetry(someFunc(1));

编译错误信息 #

No overload matches this call.
  Overload 1 of 2, '(point: Point): Point', gave the following error.
    Argument of type 'Point | undefined' is not assignable to parameter of type 'Point'.
      Type 'undefined' is not assignable to type 'Point'.
  Overload 2 of 2, '(point: undefined): undefined', gave the following error.
    Argument of type 'Point | undefined' is not assignable to parameter of type 'undefined'.
      Type 'Point' is not assignable to type 'undefined'.

修复方案 #

方案1：添加联合类型的重载签名 #

给函数新增一个接收Point | undefined参数、返回Point | undefined的重载签名，让TypeScript能匹配联合类型的输入：

type Point = { x: number; y: number }

function symetry(point : Point) : Point;
function symetry(point : undefined ) : undefined;
function symetry(point : Point | undefined) : Point | undefined; // 新增重载
function symetry(point : Point | undefined) : Point | undefined {
    if(!point) return undefined;
    return {
        x : -point.x,
        y : -point.y
    }
}

// 此时p2、p3的类型会被正确推导：p2为undefined，p3为Point
const p2 = symetry(someFunc(0));
const p3 = symetry(someFunc(1));

方案2：使用泛型关联参数与返回值 #

通过泛型让TypeScript自动根据输入类型推导返回类型，更灵活地处理联合类型：

type Point = { x: number; y: number }

function symetry<T extends Point | undefined>(point: T): T extends Point ? Point : undefined;
function symetry(point: Point | undefined): Point | undefined {
    if (!point) return undefined;
    return {
        x: -point.x,
        y: -point.y
    }
}

// 自动推导：p2为undefined，p3为Point
const p2 = symetry(someFunc(0));
const p3 = symetry(someFunc(1));

方案3：移除重载，仅保留实现签名 #

如果不需要严格的重载类型约束，可以直接去掉重载签名，只保留实现签名。缺点是传入Point类型时，返回值会被推导为Point | undefined，需要用非空断言或类型断言处理：

type Point = { x: number; y: number }

function symetry(point : Point | undefined) : Point | undefined {
    if(!point) return undefined;
    return {
        x : -point.x,
        y : -point.y
    }
}

// 使用非空断言
const p1 = symetry({x: 10, y:-4})!;
// 或类型断言
const p1 = symetry({x: 10, y:-4}) as Point;

// p2、p3类型自动推导正确
const p2 = symetry(someFunc(0));
const p3 = symetry(someFunc(1));

错误原因 #

原重载仅定义了Point和undefined两种单独的参数类型，当传入联合类型Point | undefined时，TypeScript会尝试匹配每个重载，但联合类型无法匹配任何一个单独的重载签名，因此抛出编译错误。添加联合类型重载或使用泛型，能让TypeScript正确识别并处理这种情况。

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