TypeScript带默认参数的泛型函数重载实现编译报错问题

这个TS2345类型错误的核心逻辑是：TypeScript的函数重载实现签名不会自动继承重载分支的类型约束。
你定义的两个重载签名已经正确约束了外部调用规则：

• 不传transformer参数时，返回值固定为Promise<ArrayBuffer>
• 传入transformer参数时，返回值为transformer对应的泛型返回类型Promise<T>

但在函数实现内部，TS会独立做类型校验：实现签名里的泛型T是完全开放的任意类型，默认的恒等函数x => x返回值为ArrayBuffer，TS无法证明ArrayBuffer可以兼容所有可能被实例化的T类型（毕竟调用方理论上可以把T指定为和ArrayBuffer无关的任意类型），因此抛出类型不匹配错误。

以下两种方案都可以通过类型校验，且完全保留你需要的对外调用类型约束：

方案1：分支流判断（无类型断言，类型安全最高） #

通过显式的分支判断拆分逻辑，让TS通过流分析自动匹配对应类型，同时给泛型添加默认值ArrayBuffer适配无transformer的场景：

export async function downloadWithCache(
  url: string
): Promise<ArrayBuffer>;
export async function downloadWithCache<T>(
  url: string,
  transformer: (buffer: ArrayBuffer) => T
): Promise<T>;
export async function downloadWithCache<T = ArrayBuffer>(
  url: string,
  transformer?: (buffer: ArrayBuffer) => T
): Promise<T | ArrayBuffer> {
  if (!transformer) {
    // 无transformer分支，返回ArrayBuffer
    return someImplementation(url, x => x);
  }
  // 传入transformer分支，返回T类型
  return someImplementation(url, transformer);
}

这种写法不需要任何类型断言，TS可以自动校验两个分支的类型正确性，实现签名的返回值Promise<T | ArrayBuffer>是内部实现使用的类型，不会对外暴露，外部调用依然严格遵循你定义的两个重载签名规则。

方案2：类型断言（代码最简洁） #

如果你不想拆分分支，可以通过类型断言告诉TS默认transformer符合类型约束——由于重载签名已经保证了：只有当T = ArrayBuffer时才会走到默认transformer的分支，所以这个断言是完全类型安全的：

export async function downloadWithCache(
  url: string
): Promise<ArrayBuffer>;
export async function downloadWithCache<T>(
  url: string,
  transformer: (buffer: ArrayBuffer) => T
): Promise<T>;
export async function downloadWithCache<T>(
  url: string,
  transformer?: (buffer: ArrayBuffer) => T
) {
  const defaultTransformer = (x => x) as (buffer: ArrayBuffer) => T;
  return someImplementation(url, transformer ?? defaultTransformer);
}

注意：使用类型断言需要你自己保证重载逻辑和实现逻辑一致，如果后续修改重载签名，需要同步检查断言逻辑是否依然安全。

内容的提问来源于stack exchange，提问作者Ark-kun