TypeScript 声明合并的具体使用

作者：拾光时间：2026-10-31 21:33:51浏览：652

本文深入解析 TypeScript 中的声明合并机制，涵盖接口、命名空间及模块扩展的具体用法。详细说明了成员冲突处理、函数重载规则、字面量类型优先级以及命名空间与类/函数/枚举的合并方式，并澄清了 type alias 与 interface 无法合并的限制，帮助开发者构建更灵活的类型定义。

在 TypeScript 的类型系统中，声明合并是一项独特且强大的特性，它允许编译器将多个同名的声明自动整合为一个统一的声明结构。这一机制不仅在使用现有 JavaScript 库时十分关键，也为构建复杂的类型抽象提供了极大便利。

本文将深入探讨声明合并的基本概念、常见形式、合并规则与限制，并针对 interface 和 type 等类型的同名合并情况进行具体分析。

一、什么是声明合并？

声明合并（Declaration Merging）指的是：当 TypeScript 编译器检测到多个同名的声明时，会将它们合并为一个声明，最终生成的合并声明将包含所有原始声明的特性。

简而言之，其核心逻辑是：多个同名声明 → 一个完整的复合声明。

二、接口（Interface）合并

最常见的合并形式即为接口合并。

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

interface Box {
  scale: number;
}

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

合并后的结果如下：

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

⚠️ 成员冲突规则

对于非函数成员，若名称相同但类型不同，编译器将报错。
对于函数成员，则作为函数重载进行合并，后声明的签名将排在前面。

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

合并后的最终结果：

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

📌 字面量类型优先

当函数参数包含单一字符串字面量时，该重载将被“提升”至重载列表的顶部：

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;
}

合并后的最终结果：

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

三、命名空间（Namespace）合并

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

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

合并后的结果：

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

❗ 非导出成员不可见

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

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

模块扩展（Module Augmentation）

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

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

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

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

全局扩展（Global Augmentation）

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

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

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

1. 命名空间 + 类（class）

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

此时 Album.Label 成为合法的引用方式。

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

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）

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 同名合并。

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	❌