TypeScript 声明合并和模块增强是什么？有什么风险？

简化版

声明合并是 TypeScript 把同名的接口、命名空间等声明合成一个类型；模块增强是通过 declare module 给已有模块补充类型。它常用于扩展第三方库类型，但风险是污染全局、模块名写错、类型和运行时实现不一致。

详细版

声明合并示例：

interface User {
  id: string;
}

interface User {
  name: string;
}

const u: User = { id: '1', name: 'Ada' };

模块增强示例：

declare module 'express-serve-static-core' {
  interface Request {
    user?: { id: string };
  }
}

面试重点不是背语法，而是说清楚：这只是补充类型，运行时对象上是否真的有字段，要靠中间件或业务代码赋值。

完整版教学

一、声明合并解决同名声明如何共存

TypeScript 允许某些同名声明合并成一个定义。最常见的是 interface 合并：多个同名接口会把成员叠加起来。这和 type 不同，type 别名不能在同一作用域重复声明。

interface Window {
  appVersion: string;
}

interface Window {
  track(event: string): void;
}

合并后，Window 同时拥有 appVersion 和 track。如果第 1 个接口有 2 个字段，第 2 个接口有 1 个字段，最终就有 3 个字段。这种能力对扩展全局对象和库类型很有用，但也会让类型来源变得分散。

二、interface 合并和 type 交叉不是一回事

interface 声明合并是编译器对同名声明的自动合成。 type A = X & Y 是手动创建交叉类型。二者都能得到“多个成员合在一起”的结果，但使用边界不同。

interface Config {
  debug: boolean;
}

interface Config {
  logLevel: 'info' | 'warn' | 'error';
}

type Config2 = {
  debug: boolean;
} & {
  logLevel: 'info' | 'warn' | 'error';
};

对比项	声明合并	交叉类型
触发方式	同名 interface 等自动合并	显式使用 `&`
常见用途	扩展库、全局对象、模块类型	组合业务类型
可读性风险	类型来源分散	组合处更清楚
是否能重复声明	interface 可以	type 不可以

业务代码里更推荐显式交叉或组合；扩展第三方类型时才更常用声明合并。

三、模块增强是在已有模块上补类型

模块增强使用 declare module '模块名'。它告诉 TypeScript：某个已经存在的模块，其导出类型还可以补充。典型例子是给 Express Request、NextAuth Session、Vue ComponentCustomProperties 添加项目字段。

declare module 'next-auth' {
  interface Session {
    user: {
      id: string;
      role: 'admin' | 'user';
    };
  }
}

这段代码只影响类型系统。如果登录回调里没有真的把 id 和 role 放进 session，运行时依然拿不到。所以回答模块增强时，一定要把“类型增强”和“运行时赋值”拆开讲。

四、模块名必须和真实解析结果一致

模块增强最容易错的是模块名。 declare module 'foo' 里的字符串必须和项目中 import 的模块解析一致。如果库的类型实际声明在子路径里，增强顶层包名可能不会生效。

// 业务代码实际使用
import type { Request } from 'express-serve-static-core';

// 增强也要对准这个模块
declare module 'express-serve-static-core' {
  interface Request {
    traceId?: string;
  }
}

排查流程可以这样走：

找到业务 import 来源
  -> 找到库的 .d.ts 实际声明位置
  -> declare module 写同一个模块名
  -> 确认增强文件被 tsconfig include
  -> 重启 TS Server 或 IDE

很多“我写了增强但不生效”的问题，最后都是模块名不准或文件没被 tsconfig 包含。

五、全局增强要放进 declare global

如果要扩展全局类型，例如 Window、ImportMetaEnv，常见写法是在模块文件里使用 declare global。为了让文件本身成为模块，通常会加一个空导出 export {}。这样可以避免声明意外落入脚本作用域。

export {};

declare global {
  interface Window {
    __APP_CONFIG__: {
      apiBase: string;
    };
  }
}

记忆钩子：增强第三方模块找 declare module，增强全局对象找 declare global，两者都只补类型不补实现。

例如页面运行时必须真的执行：

window.__APP_CONFIG__ = {
  apiBase: 'https://api.example.com',
};

否则类型上能访问，运行时仍然可能是 undefined。

六、声明合并的风险是类型污染和契约漂移

声明合并很强，但不应该滥用。如果到处增强全局接口，任何文件都可能“凭空”多出字段，代码读者很难追踪来源。更严重的是，类型增强可能和运行时实现脱节。

declare global {
  interface Window {
    pay(): Promise<boolean>;
  }
}

// 如果真实脚本没有注入 window.pay，调用会运行时失败

一个团队约定很实用：所有全局增强集中放在 src/types 或 global.d.ts，并在旁边标注对应的运行时注入位置。如果一个字段只在局部函数中使用，优先用局部类型组合，不要污染全局。声明合并应该服务于边界集成，而不是替代正常的类型设计。

七、常见误区与追问

误区：声明合并会给对象真的加字段。 它只改变类型视角，运行时字段仍需要真实代码赋值或第三方库提供。
误区：type 和 interface 都能重复声明合并。 同一作用域下 interface 可以合并，type 重复声明会报错。
误区：模块增强不生效就是 TypeScript 坏了。 更常见原因是模块名写错、增强文件没被 tsconfig 包含、IDE TS Server 没刷新。
追问：模块增强适合什么场景？ 适合扩展第三方库类型、框架上下文、全局环境变量、插件注入字段等边界场景。
追问：为什么模块增强有风险？ 因为类型可以被全局改变，来源分散后可读性下降，还可能和运行时行为不一致。
追问：如何降低声明合并的维护成本？ 集中管理增强文件，命名清晰，对应运行时注入位置，并避免在普通业务类型里滥用。

八、加强记忆

这题记成“三层边界”：同名 interface 可以合并，这是语言能力；declare module 给已有模块补类型，这是库集成能力；declare global 给全局对象补类型，这是环境建模能力。最后必须补一句：它们都只发生在类型层，运行时有没有字段，要看真实代码。

简化版

详细版