如何在.d.ts文件中根据参数变化匹配函数正确返回类型？

你的问题出在重载签名的写法上：给每个重载都加了默认值，导致TypeScript优先匹配第一个签名（因为false也符合第一个签名的boolean类型约束），无法正确根据参数推断返回类型。下面是两种场景的正确写法：

1. 在.d.ts声明文件中定义 #

把参数更具体的重载放在前面，默认值只在最宽泛的签名中处理：

declare class YourClass {
  /** 传入false时返回object */
  static someFunc(str: string, bool: false): object;
  /** 传入true或不传时返回array */
  static someFunc(str: string, bool?: true): array;
}

这样调用时：

• YourClass.someFunc('string', false) → 返回类型推断为object
• YourClass.someFunc('string', true) 或 YourClass.someFunc('string') → 返回类型推断为array

2. 在纯JS文件中用JSDoc #

使用@overload标签明确区分不同参数对应的返回类型，默认值只写在实现函数的JSDoc里：

/**
 * @overload
 * @param {string} str
 * @param {false} bool
 * @returns {object}
 */
/**
 * @overload
 * @param {string} str
 * @param {true} [bool]
 * @returns {array}
 */
/**
 * @param {string} str
 * @param {boolean} [bool=true]
 * @returns {array|object}
 */
static someFunc(str, bool = true) {
  if (bool) {
    return [];
  }
  return {};
}

核心逻辑：重载匹配是按顺序进行的，必须把参数约束更严格的重载放在前面，让TypeScript能精准匹配到对应的返回类型；默认值不要分散在各个重载签名中，只在最通用的签名或实现里声明即可。

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