TypeScript声明合并的多种使用方式
本文深入解析TypeScript中的声明合并机制，涵盖接口、枚举、类、命名空间及模块的全方位合并规则。详细阐述同名声明在值、类型和命名空间层面的合并逻辑，包括接口重载优先级、枚举初始值计算限制、类与接口合并以及命名空间与函数/类的组合技巧，并介绍利用模块扩充语法扩展第三方库类型的方法。
声明构成编程语言的基石，用于界定标识符的具体指代。在TypeScript中，标识符具备三种核心含义：
- 代表具体的值。
- 代表特定的类型。
- 代表命名空间。
下文示例分别构建了值、类型及命名空间。其中，常量zero归为值，接口Point归为类型，而命名空间Utils归为命名空间。具体示例如下：
const zero = 0;
interface Point {
x: number;
y: number;
}
namespace Utils {}
针对同一标识符，其可同时承载上述多重含义。以标识符A为例，它既可表示值，也可表示类型，还能表示命名空间。具体示例如下：
const A = 0;
interface A {}
namespace A {}
在相同声明空间内，标识符必须保持唯一性。TypeScript中多数语法结构（如函数或类声明）均可创建新的声明空间，其中全局与模块声明空间最为典型。若编译器检测到同一空间内存在同名声明，将尝试执行合并操作；若无法合并，则触发编译错误。此行为为TypeScript独有。合并过程中，编译器依据标识符含义分组处理，即值与值、类型与类型、命名空间与命名空间分别合并。需注意，部分同名声明（如常量a与函数a）不允许合并。
下文将详细阐述TypeScript中的声明合并机制，涵盖接口、枚举、类、命名空间、扩充模块及全局声明等场景。
1、接口声明合并
接口声明为标识符赋予类型语义。在同一声明空间内，多个同名接口将自动合并为一个接口。以下示例包含两个A接口声明，且处于同一空间。编译器会将两者的类型成员整合，合并后的接口A等效于MergedA。具体示例如下：
interface A {
a: string;
}
interface A {
b: number;
}
interface MergedA {
a: string;
b: number;
}
若待合并接口中包含同名属性签名成员，则这些成员的类型必须一致，否则因冲突导致编译错误。例如，以下两个A接口中，属性a的类型分别为number与string，合并时将引发冲突。具体示例如下：
interface A {
a: number;
}
interface A {
a: string; // 编译错误
}
若待合并接口中包含同名方法签名成员，这些成员将被视为函数重载，且后定义的方法签名优先级更高。例如，以下两个A接口均定义了方法f。合并后的接口A中，f拥有两个重载签名，且后声明的f（第6行）优先级更高。具体示例如下：
interface A {
f(x: any): void;
}
interface A {
f(x: string): boolean;
}
interface MergedA {
f(x: string): boolean;
f(x: any): void;
}
合并重载签名的核心原则是后声明者优先级更高。但存在例外：若参数类型包含字面量类型，则该重载签名优先级更高。例如，以下示例中尽管第2行的f先声明，但因函数签名包含字面量类型，合并后其优先级仍高于第4行的f。具体示例如下：
interface A {
f(x: 'foo'): boolean;
}
interface A {
f(x: any): void;
}
interface MergedA {
f(x: 'foo'): boolean;
f(x: any): void;
}
若待合并接口中包含多个调用签名或构造签名成员，它们将被视为函数重载和构造函数重载。处理逻辑与方法签名合并一致：后声明的成员优先级更高，同时需考量参数类型是否包含字面量类型。具体示例如下：
interface A {
new (x: any): object;
(x: any): any;
}
interface A {
new (x: string): Date;
(x: string): string;
}
interface MergedA {
new (x: string): Date;
new (x: any): object;
(x: string): string;
(x: any): any;
}
涉及重载时，接口合并的顺序至关重要，因为它直接决定重载的解析顺序。
若待合并接口中包含多个字符串索引签名或数值索引签名，将直接导致编译错误。合并规则要求所有接口中仅允许存在一个字符串索引签名和一个数值索引签名。具体示例如下：
interface A {
[prop: string]: string;
}
interface A {
[prop: number]: string;
}
interface MergedA {
[prop: string]: string;
[prop: number]: string;
}
若待合并接口为泛型接口，则所有同名接口必须拥有完全一致的类型参数列表。若存在继承关系，所有继承接口将合并为单一父接口。实际开发中，建议避免复杂接口的合并行为，以防代码可读性下降。
2、枚举声明合并
多个同名枚举声明将合并为一个枚举。合并时，仅允许其中一个枚举的首个成员省略初始值。具体示例如下：
enum E {
A,
}
enum E {
B = 1,
}
enum E {
C = 2,
}
let e: E;
e = E.A;
e = E.B;
e = E.C;
本例中，第2行的首个枚举成员省略了初始值，TypeScript将自动计算其值。而第6行和第10行的首个枚举成员必须显式定义初始值，否则因编译器无法在多个同名枚举间自动计算值而报错。
枚举合并的另一限制是：所有同名枚举声明必须同为const枚举或非const枚举，严禁混合使用。具体示例如下：
// 正确
enum E0 {
A,
}
enum E0 {
B = 1,
}
// 正确
const enum E1 {
A,
}
const enum E1 {
B = 1,
}
// 编译错误
enum E2 {
A,
}
const enum E2 {
B = 1,
}
3、类声明合并
TypeScript禁止合并同名类声明，但允许外部类声明与接口声明合并，合并后的类型即为类类型。具体示例如下：
declare class C {
x: string;
}
interface C {
y: number;
}
let c: C = new C();
c.x;
c.y;
4、命名空间声明合并
命名空间的合并机制相对复杂，支持与命名空间、函数、类及枚举进行合并。
4.1 命名空间与命名空间合并
与接口合并类似，同名命名空间也会执行合并。例如，编译器会将以下两个Animals命名空间合并，结果等同于MergedAnimals。具体示例如下：
namespace Animals {
export class Bird {}
}
namespace Animals {
export interface CanFly {
canFly: boolean;
}
export class Dog {}
}
namespace MergedAnimals {
export interface CanFly {
canFly: boolean;
}
export class Bird {}
export class Dog {}
}
若存在嵌套命名空间，合并外层命名空间时，同名的内层命名空间也会同步合并。具体示例如下：
namespace outer {
export namespace inner {
export var x = 10;
}
}
namespace outer {
export namespace inner {
export var y = 20;
}
}
namespace MergedOuter {
export namespace inner {
export var x = 10;
export var y = 20;
}
}
合并命名空间声明时，其中的非导出成员不会被合并，仅限在各自命名空间内访问。具体示例如下：
namespace NS {
const a = 0;
export function foo() {
a; // 正确
}
}
namespace NS {
export function bar() {
foo(); // 正确
a; // 编译错误：找不到 'a'
}
}
4.2 命名空间与函数合并
同名命名空间声明与函数声明可合并，但要求函数声明必须位于命名空间声明之前，以确保先创建函数对象。此操作相当于为函数对象添加额外属性。具体示例如下：
function f() {
return f.version;
}
namespace f {
export const version = '1.0';
}
f(); // '1.0'
f.version; // '1.0'
4.3 命名空间与类合并
同名命名空间声明与类声明可合并，但要求类声明必须位于命名空间声明之前，以确保先创建构造函数对象。此机制提供了一种创建内部类的方式。具体示例如下：
class Outer {
inner: Outer.Inner = new Outer.Inner();
}
namespace Outer {
export class Inner {}
}
亦可利用命名空间与类的合并来为类添加静态属性和方法。具体示例如下：
class A {
foo: string = A.bar;
}
namespace A {
export let bar = 'A';
export function create() {
return new A();
}
}
const a: A = A.create();
a.foo; // 'A'
A.bar; // 'A'
4.4 命名空间与枚举合并
同名命名空间声明与枚举声明可合并，这相当于将枚举成员与命名空间的导出成员进行合并。具体示例如下：
enum E {
A,
B,
C,
}
namespace E {
export function foo() {
E.A;
E.B;
E.C;
}
}
E.A;
E.B;
E.C;
E.foo();
需注意，枚举成员名与命名空间导出成员名不得同名。具体示例如下：
enum E {
A, // 编译错误！重复的标识符 A
}
namespace E {
export function A() {} // 编译错误！重复的标识符 A
}
5、扩充模块声明
利用模块扩充语法，可对任意模块内的现有声明进行扩展。例如，在“a.ts”中定义接口A后，可在“b.ts”中对其扩展，增加新属性。
假设工程目录结构如下：
C:\app
|-- a.ts
`-- b.ts
“a.ts”模块文件内容如下：
export interface A {
x: number;
}
“b.ts”模块文件内容如下：
import { A } from './a';
declare module './a' {
interface A {
y: number;
}
}
const a: A = { x: 0, y: 0 };
本例中，“declare module ‘./a’ {}”为模块扩充语法。其中，“‘./a’”指代要扩充的模块名，需与第一行导入语句中的模块名一致。
我们利用模块扩充语法对导入模块“‘./a’”进行了扩展。第4行定义的接口A将与“a.ts”中的接口A合并，结果仍为接口A，但增加了属性成员y。
使用模块扩充语法时需注意以下两点：
- 模块扩充语法中不得增加新的顶层声明，仅能扩充现有声明。即只能对“‘./a’”中已存在的接口A进行扩充，禁止新增声明（如定义新接口B）。
- 无法使用模块扩充语法扩充模块的默认导出，仅能扩充命名导出，因为扩充操作依赖于导出的名称。
6、扩充全局声明
与模块扩充类似，TypeScript提供了全局对象扩充语法“declare global {}”。具体示例如下：
export {};
declare global {
interface Window {
myAppConfig: object;
}
}
const config: object = window.myAppConfig;
本例中，“declare global {}”为全局对象扩充语法，用于扩展全局Window对象并增加myAppConfig属性。第1行使用“export {}”空导出语句，是因为全局扩充语句必须在模块或外部模块声明中使用，添加空导出后该文件即被视为模块。
全局对象扩充同样受限于模块扩充规则：不得在语法中增加新的顶层声明，仅能扩充现有声明。
至此，关于TypeScript声明合并多种使用方式的介绍已结束。如需了解更多TypeScript声明合并内容，请查阅本站往期文章或继续浏览后续相关文章，感谢大家的支持！
5款主流JS在线运行工具对比：CodePen、JSFiddle与StackBlitz怎么选
2026-11-05 17:04:04
JavaScript入门书籍避坑：这些书不适合初学者
2026-11-05 16:31:15
JS使用Math.round实现保留两位小数的原理与代码
2026-11-05 15:35:55
JavaScript 原生 Date 对象怎么实现日期加减
2026-11-05 14:30:00
JavaScript函数定义的三种方式：声明、表达式与箭头函数
2026-11-05 13:50:55
