为何TypeScript泛型索引会推断为交叉类型而非联合类型？

问题重现 #

先定义基础类型与变量：

export type IPage = {
    title: string;
};

export type IArticle = {
    title: string;
    body: string;
};

export type PageTypesMap = {
    'page': IPage;
    'article': IArticle;
};

export const pageContentTypesEndpoints = {
    'page': 'pages',
    'article': 'articles',
} as const;

export type PageTypesWithContentType = {
    [key in keyof PageTypesMap]: PageTypesMap[key] & { __contentType: key };
};

export type PageTypes = {
    [key in keyof PageTypesMap]: PageTypesMap[key];
};

直接使用PageTypesWithContentType['page' | 'article']可以得到预期的联合类型(IPage & {__contentType: 'page'}) | (IArticle & {__contentType: 'article'})，但在泛型函数中做类似操作时出现错误：

const setContentType = <ContentType extends keyof typeof pageContentTypesEndpoints>(
    page: PageTypes[ContentType],
    contentType: ContentType
): PageTypesWithContentType[ContentType] => {
    const result: PageTypesWithContentType[ContentType] = {
        ...page,
        __contentType: contentType,
    };
    return result;
};

错误信息 #

Type 'PageTypes[ContentType] & { __contentType: ContentType; }' is not assignable to type 'PageTypesWithContentType[ContentType]'.
  Type 'PageTypes[ContentType] & { __contentType: ContentType; }' is not assignable to type 'never'.
    The intersection 'IPage & { __contentType: "page"; } & IArticle & { __contentType: "article"; }' was reduced to 'never' because property '__contentType' has conflicting types in some constituents.

核心疑问：为什么直接访问联合索引能得到正确的联合类型，而泛型中却被推断为冲突的交叉类型？即使将泛型约束改为'page' | 'article'，错误依然存在。

原因分析 #

这是TypeScript处理泛型参数与直接索引联合类型的逻辑差异导致的：

1. 直接索引联合类型的逻辑：
   当你写PageTypesWithContentType['page' | 'article']时，TypeScript会执行索引访问联合类型的规则：自动将联合索引拆分为单个成员，分别获取对应类型后再合并为联合类型，最终得到(IPage & {__contentType: 'page'}) | (IArticle & {__contentType: 'article'})，完全符合预期。

2. 泛型参数的处理逻辑：
   泛型参数ContentType被约束为keyof PageTypesMap（即'page' | 'article'）时，TypeScript会将其视为一个单一的类型变量——它可以是联合中的任意单个成员，也可以是整个联合。此时TypeScript不会自动对联合进行拆分处理，而是会将PageTypes[ContentType]解析为所有对应值类型的交叉（即IPage & IArticle），同时__contentType: ContentType会被解析为__contentType: 'page' & 'article'（这本身就是never类型）。两者交叉后自然变成never，因此出现了类型不兼容的错误。

简单来说，泛型参数不会主动触发联合类型的分布式处理，而是被当作一个“涵盖所有可能成员的集合”，导致了错误的交叉类型推导。

解决方案 #

方案1：使用类型断言 #

因为我们明确知道代码逻辑的正确性，只是TypeScript无法自动识别这种映射关系，可以直接用类型断言绕过推导限制：

const setContentType = <ContentType extends keyof typeof pageContentTypesEndpoints>(
    page: PageTypes[ContentType],
    contentType: ContentType
): PageTypesWithContentType[ContentType] => {
    return {
        ...page,
        __contentType: contentType,
    } as PageTypesWithContentType[ContentType];
};

方案2：利用分布式条件类型 #

通过定义分布式条件类型，强制TypeScript对联合类型进行拆分处理：

// 定义分布式条件类型，自动处理联合类型的拆分与合并
type AddContentType<T extends keyof PageTypesMap> = T extends keyof PageTypesMap 
  ? PageTypesMap[T] & { __contentType: T } 
  : never;

const setContentType = <ContentType extends keyof PageTypesMap>(
    page: PageTypes[ContentType],
    contentType: ContentType
): AddContentType<ContentType> => {
    return {
        ...page,
        __contentType: contentType,
    } as AddContentType<ContentType>;
};

这里的条件类型T extends keyof PageTypesMap ? ... : never会触发TypeScript的分布式特性：当T是联合类型时，自动拆分为单个成员逐个处理，最终合并为正确的联合类型。

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