TypeScript中JSDoc @template结合类型联合与Required工具类型的类型推断异常问题

我来帮你拆解这个问题——你遇到的核心问题其实和泛型类型推断的优先级以及字面量类型窄化有关，咱们一步步捋清楚：

问题根源：泛型T的推断结果不是你想的那样 #

当你调用exchangeMessage({ type: 'a' })时，TypeScript并没有把泛型T推断为AMessage，而是推断成了字面量类型{ type: 'a' }。这是因为TypeScript的类型推断会优先选择最具体的类型，而不是主动去匹配你定义的联合类型Message中的成员。

你可能会疑惑：“这个字面量明明符合AMessage的结构啊？” 没错，但TypeScript不会自动把一个字面量类型“提升”到联合类型的成员——除非你给它明确的提示。

而Required<T>作用在{ type: 'a' }上时，这个类型里根本没有optionalNumber字段，所以Required<T>的结果还是{ type: 'a' }，自然你就没法访问message.optionalNumber了。

为什么纯TS环境下也会复现？ #

这个问题和JSDoc无关，纯TypeScript里同样会出现：

type AMessage = { type: 'a'; optionalNumber?: number; };
type BMessage = { type: 'b'; optionalString?: string; };
type Message = AMessage | BMessage;

async function exchangeMessage<T extends Message>(message: T): Promise<Required<T>> {
  return Promise.resolve(message as Required<T>);
}

const message = await exchangeMessage({ type: 'a' });
// message的类型是Required<{ type: "a"; }>，依然没有optionalNumber

本质还是一样的：T被推断为字面量类型，而非AMessage。

解决方案：引导TypeScript推断到联合类型的成员 #

要解决这个问题，核心是让TypeScript把T推断为Message联合中的具体成员，而不是窄化后的字面量类型，有几种可行的方式：

1. 显式标注入参的类型（最直接） #

在调用时用JSDoc的@type给入参明确标注类型，强制T推断为AMessage：

const message = await exchangeMessage(/** @type {AMessage} */{ type: 'a' });
// 现在message的类型是Required<AMessage>，可以正常访问optionalNumber了

2. 修改泛型返回类型，基于入参的type字段做条件推断 #

通过条件类型，让函数根据入参的type字段，自动匹配对应联合成员的Required类型：

/** @typedef {{ type: 'a'; optionalNumber?: number; }} AMessage */
/** @typedef {{ type: 'b'; optionalString?: string; }} BMessage */
/** @typedef {AMessage | BMessage} Message */

/**
 * @template {Message} T
 * @param {T} message
 * @returns {Promise<T extends AMessage ? Required<AMessage> : Required<BMessage>>}
 */
async function exchangeMessage(message) {
  return new Promise((resolve, reject) => { /* … */ });
}

const messageA = await exchangeMessage({ type: 'a' });
messageA.optionalNumber; // 现在可以正常访问
const messageB = await exchangeMessage({ type: 'b' });
messageB.optionalString; // 同样正常

这种方式不需要显式标注入参类型，TypeScript会根据type字段自动关联到对应的联合成员，再应用Required转换。

3. 调整函数参数类型为Message（放弃泛型的精确推断） #

如果你不需要严格的“入参类型和返回类型完全一致”，可以直接把参数类型设为Message，返回对应分支的Required类型：

/**
 * @param {Message} message
 * @returns {Promise<Required<AMessage> | Required<BMessage>>}
 */
async function exchangeMessage(message) {
  return new Promise((resolve, reject) => { /* … */ });
}

不过这种方式的类型精确性稍差，返回类型是联合类型，需要用类型守卫区分type字段后才能访问对应属性。

总结 #

TypeScript不会自动把字面量类型关联到你定义的联合类型成员，泛型推断的优先级是“最具体的传入值类型”。要让Required<T>生效，必须确保T是联合类型中的具体成员，而不是窄化后的字面量类型——要么显式标注类型，要么通过条件类型引导推断。

内容的提问来源于stack exchange，提问作者Tomáš Hübelbauer