TypeScript 声明合并（Declaration Merging）详解

在 TypeScript 的类型系统中，声明合并是一个非常独特且强大的特性，它让多个同名的声明可以被自动合并成一个统一的声明结构。这种机制不仅在使用现有 JavaScript 库时非常有用，也为构建复杂的类型抽象提供了便利。

本文将详细介绍声明合并的基本概念、常见形式、合并规则、限制，以及对你可能关心的问题如 interface 和 type 的同名情况进行探讨。

一、什么是声明合并？

声明合并 （Declaration Merging）是指：当 TypeScript 编译器遇到多个同名的声明时，会将它们合并为一个声明，最终这个合并声明具备所有原始声明的特性。

简而言之，就是多个同名声明 → 一个完整的复合声明。

二、接口（Interface）合并

最常见的合并形式就是接口合并。

ts 复制代码

interface Box {
  height: number;
  width: number;
}

interface Box {
  scale: number;
}

const box: Box = { height: 10, width: 20, scale: 1.5 };

合并结果为：

ts 复制代码

interface Box {
  height: number;
  width: number;
  scale: number;
}

⚠️ 成员冲突规则

如果是非函数成员，名称相同但类型不同会报错。
如果是函数成员，将作为函数重载合并，后声明的排在前面。

ts 复制代码

interface Cloner {
  clone(animal: Animal): Animal;
}
interface Cloner {
  clone(animal: Dog): Dog;
  clone(animal: Cat): Cat;
}

合并结果：

ts 复制代码

interface Cloner {
  clone(animal: Dog): Dog;
  clone(animal: Cat): Cat;
  clone(animal: Animal): Animal;
}

📌 字面量类型优先

当函数参数是单一字符串字面量时，重载将被"提升"至重载列表顶部：

ts 复制代码

interface Document {
  createElement(tagName: any): Element;
}
interface Document {
  createElement(tagName: "div"): HTMLDivElement;
  createElement(tagName: "span"): HTMLSpanElement;
}
interface Document {
  createElement(tagName: string): HTMLElement;
  createElement(tagName: "canvas"): HTMLCanvasElement;
}

合并结果：

ts 复制代码

interface Document {
  createElement(tagName: "canvas"): HTMLCanvasElement;
  createElement(tagName: "div"): HTMLDivElement;
  createElement(tagName: "span"): HTMLSpanElement;
  createElement(tagName: string): HTMLElement;
  createElement(tagName: any): Element;
}

三、命名空间（Namespace）合并

多个同名的 namespace 可以合并，其成员最终被聚合为一个命名空间：

ts 复制代码

namespace Animals {
  export class Dog {}
}
namespace Animals {
  export interface Legged {
    numberOfLegs: number;
  }
}

合并结果为：

ts 复制代码

namespace Animals {
  export class Dog {}
  export interface Legged {
    numberOfLegs: number;
  }
}

❗ 非导出成员不可见

ts 复制代码

namespace Animal {
  let hidden = true;
  export function canSeeHidden() {
    return hidden; // ✅ OK
  }
}
namespace Animal {
  export function tryToAccessHidden() {
    return hidden; // ❌ 报错
  }
}

四、模块与全局声明扩展（Augmentation）

模块扩展（Module Augmentation）

ts 复制代码

// observable.ts
export class Observable<T> {}

ts 复制代码

// map.ts
import { Observable } from './observable';

declare module './observable' {
  interface Observable<T> {
    map<U>(fn: (x: T) => U): Observable<U>;
  }
}

不能新增顶级声明，只能扩展现有结构，且仅支持具名导出。

全局扩展（Global Augmentation）

ts 复制代码

declare global {
  interface Array<T> {
    toObservable(): Observable<T>;
  }
}

五、命名空间与其他类型合并

TypeScript 支持将命名空间与某些其他类型进行合并，常见于表达"内部类"、"静态成员扩展"等高级模式。

1. 命名空间 + 类（class）

ts 复制代码

class Album {
  label: Album.Label;
}
namespace Album {
  export class Label {}
}

现在 Album.Label 是一个合法的引用。

2. 命名空间 + 函数（function）

ts 复制代码

function buildLabel(name: string): string {
  return buildLabel.prefix + name + buildLabel.suffix;
}
namespace buildLabel {
  export let prefix = "Hello, ";
  export let suffix = "!";
}

支持 buildLabel("TypeScript") 与 buildLabel.prefix 等调用。

3. 命名空间 + 枚举（enum）

ts 复制代码

enum Color {
  Red = 1,
  Green = 2,
}
namespace Color {
  export function mix(): number {
    return Color.Red + Color.Green;
  }
}

这样我们就可以使用 Color.mix() 作为枚举的"静态方法"。

六、type alias 与 interface 能否合并？

这是许多开发者关心的问题：TypeScript 不支持 type 与 interface 同名合并。

ts 复制代码

interface Foo {
  x: number;
}
type Foo = { y: number }; // ❌ 报错：重复标识符 "Foo"

目前为止，interface 与 interface 可以合并，namespace 与其他部分类型也可以合并，但 type 与 interface 属于不同的结构，不能合并。

七、总结

合并类型	是否支持
interface 与 interface	✅
namespace 与 namespace	✅
namespace 与 class	✅
namespace 与 function	✅
namespace 与 enum	✅
type alias 与 interface	❌
class 与 class	❌
class 与 variable	❌

声明合并是 TypeScript 类型系统中的一项核心机制，熟练掌握它不仅可以更好地使用第三方类型定义，还能让我们构建更强大、灵活的类型表达。

八、参考资料

Declaration Merging