TypeScript declare module同名类型别名扩展不生效问题

你的写法存在三个关键问题，不符合TypeScript的类型系统规则：

• 模块增强（Module Augmentation）的语法错误：declare module 代码块内部的类型声明不需要额外加declare关键字，多余的declare会导致声明无法被TS识别为合并项。
• 本地模块的路径匹配错误：你在./myLib/index.d.ts中定义的类型，对应的模块标识是相对路径./myLib，你在类型文件中写declare module "myLib"相当于声明了一个和本地文件完全无关的全新顶级模块，根本不会和现有本地模块的类型做合并，自然无法生效。
• 违反TypeScript声明合并的基础规则：类型别名（type定义）不支持声明合并，无论是你自定义的MyType还是Next.js的NextPage，只要它是通过type定义的别名，就无法通过模块增强的方式重写、扩展原有定义，只有interface、namespace、class 这几类结构支持跨块声明合并。

场景1：扩展本地自定义模块类型 #

如果要让本地模块的类型支持扩展，有两种可选方案：

1. 将需要扩展的类型改为interface（推荐，支持自动合并）
   首先修改原模块的类型定义：

   // .../src/myLib/index.d.ts
   // 替换type为支持合并的interface
   export interface MyType { 
     field1: string 
   }
   

   然后在全局类型文件中写模块增强，注意模块路径必须和你导入时写的路径一致，内部不要加多余的declare：

   // .../src/types.d.ts
   declare module "./myLib" {
     interface MyType {
       field2: number
     }
   }
   

   正常导入使用时类型会自动合并，两个字段都会被正确识别：

   import {MyType} from "./myLib";
   
   let x: MyType = {
     field1: "myString",
     field2: 15,
   }
   

2. 如果不想修改原类型为interface，就不要尝试覆盖原有类型，直接定义一个新的扩展类型使用即可：

   // .../src/types.d.ts
   export type MyExtendedType = import("./myLib").MyType & { field2: number }
   

   使用时直接导入这个新的扩展类型即可。

场景2：扩展第三方模块（如next）类型 #

第三方模块导出的类型如果是type别名，同样不支持直接合并覆盖，不要尝试重写原导出项，直接自定义一层扩展类型使用即可：

// .../src/types.d.ts
import type { NextPage } from "next";
export type CustomNextPage<Props = {}, InitialProps = Props> = NextPage<Props, InitialProps> & {
  field2: number;
};

使用时导入你自定义的CustomNextPage代替原模块的NextPage即可。
注意：所有自定义的.d.ts文件必须被包含在tsconfig.json的include配置范围内，否则TS不会加载这些类型声明。

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