我在 TypeScript 里定义了一个 interface 描述配置对象、本以为它就是我写的那几个字段,结果某天发现它莫名其妙多出了几个我从没声明过的字段、传值时少给这些字段还报错,排查很久才搞懂项目里别处有一个同名的 interface、而 TypeScript 把这两个同名接口悄悄合并成了一个的深度复盘

这次踩的坑很魔幻:我盯着自己写的 interface 定义,数来数去就那几个字段,可编译器却坚持说它还有别的字段。我一度以为编译器疯了,直到发现——我的这个接口,早被别处一个同名接口"悄悄合体"了。

故障现场:interface 凭空多出我没写过的字段

我定义了一个 interface 来描述一份配置:

// 我在 config.ts 里写的, 自以为它就这俩字段
interface AppConfig {
  name: string;
  timeout: number;
}

const cfg: AppConfig = { name: "svc", timeout: 30 };
// 编译报错!Property 'retries' is missing in type ... required in 'AppConfig'
// retries??? 我根本没在 AppConfig 里写过 retries 啊?!

我当场就懵了,一连串问号:

• 凭空多出没写过的字段:我的 AppConfig 明明只有 name 和 timeout,可编译器报错说我少了一个 retries 字段——这个 retries 我从来没在 AppConfig 里声明过。
• 没有"重复定义"的报错:我搜了一下,发现另一个文件里也有一个 interface AppConfig(别人写的、或某个地方扩展的),里面有 retries;可奇怪的是,两个同名 interface 居然不报"重复定义"的错。
• 字段被合并了:细看才发现,我能访问的 AppConfig,是两个同名 interface 的字段合并——我的 name/timeout,加上那边的 retries,凑成了一个"四不像"。
• 换成 type 就报冲突了:我试着把我的 interface 改成 type AppConfig = {...},这下立刻报错了:"Duplicate identifier 'AppConfig'"——type 重名会冲突,interface 重名却合并。

"同名 interface 不报冲突反而合并、字段被凑到一起、换成 type 就报重复"——这几条合起来,指向一个我从没听说过的 TypeScript 特性:两个同名的 interface,TypeScript 不会当成冲突报错,而是把它们的成员自动合并成一个 interface。我得去搞清楚,这个"自动合并"到底是怎么回事、为什么会有这种设计。

第一件事:搞懂 interface 的"声明合并",同名即合并而非冲突

带着"同名 interface 被合并"这条线去查 TypeScript,我才知道这是个有名有姓、还是有意设计的特性——声明合并(declaration merging):当 TypeScript 遇到多个同名的 interface(以及 namespace 等)声明时,它不会报"重复定义"的错,而是把它们的成员合并到一个 interface 里。

也就是说,只要叫同一个名字,无论写在哪个文件、哪个角落,这些 interface AppConfig 的所有字段都会被汇总到一个 AppConfig 里:

• 我写的 interface AppConfig { name; timeout };
• 别处写的 interface AppConfig { retries };
• TypeScript 把它们合并成 AppConfig { name; timeout; retries }——我用到的就是这个合并后的版本。

为什么 TS 要这么设计?因为"声明合并"是一个极其有用的扩展机制:它让你能够给一个你无法修改源码的类型"打补丁"——比如给第三方库的 interface 加字段、给全局的 Window 接口加自定义属性、给 Express 的 Request 加你挂上去的字段。你只要在自己代码里写一个同名 interface,把要加的字段写进去,TS 就会把它合并进原来的类型。这是 TS 类型系统开放扩展的招牌能力。

可这个"开放扩展"的能力,有它的另一面:正因为"同名即合并",两个本来意图不同、只是恰好重名的 interface,也会被毫无征兆地合并到一起——TS 不会报"重名冲突"来提醒你,而是默默地把它们揉成一个。我和那个别处的 AppConfig,本是两个毫不相干的配置定义,只因为撞了名,就被 TS 合并成了一个不伦不类的类型,于是我的接口凭空多出了 retries。我把这个合并验证清楚:

// 文件 a.ts
interface AppConfig { name: string; timeout: number; }
// 文件 b.ts (别处, 不同意图却同名)
interface AppConfig { retries: number; }

// TS 把两者合并, 任何地方用到的 AppConfig 都是:
// interface AppConfig { name: string; timeout: number; retries: number; }
const c: AppConfig = { name: "x", timeout: 1, retries: 3 };  // 三个字段都要!

// 对照:type 不会声明合并, 重名直接冲突报错
type T = { a: number };
// type T = { b: number };   // ❌ Duplicate identifier 'T'

真相大白:不是编译器疯了,而是 TypeScript 的 interface 有"声明合并"特性——同名 interface 不冲突而是合并;这本是为"扩展第三方/全局类型"设计的好能力,可当两个意图不同的 interface 不小心撞名时,它就悄无声息地把它们揉成一个,让我的接口凭空多出了别处的字段。

第二件事:正解——不想被合并就用 type,要扩展才用 interface 声明合并

根因是"interface 同名即合并、意图不同也会被揉到一起",那正解的核心就一句话:分清你要的是"一个不容别人插手的封闭定义"还是"一个欢迎扩展的开放定义",前者用 type(重名直接冲突报错、杜绝意外合并),后者才用 interface(并刻意利用声明合并去扩展)。

// 1) 想要"封闭、不被意外合并"的类型:用 type(重名会报 Duplicate identifier)
type AppConfig = { name: string; timeout: number; };
// 别处再写 type AppConfig = {...} 会立刻冲突报错, 逼你改名 -> 不会被悄悄合并

// 2) 确实要扩展第三方/全局类型: 才有意地用 interface 声明合并
//    比如给 Express Request 挂自定义字段(这正是声明合并的正当用途)
declare global {
  namespace Express {
    interface Request { userId?: string; }   // 合并进 Express 的 Request
  }
}

// 3) 命名上做隔离, 降低撞名概率
//    模块化导出(export)、加业务前缀、放各自命名空间, 别用大路货名字当全局 interface
export interface OrderServiceConfig { /* ... */ }   // 带语境的名字, 不易撞

这里的关键判断是:这个类型,是不是只应该由我一个地方定义、不希望任何别处插手?

• 是(绝大多数业务类型):用 type——它不参与声明合并,重名直接冲突报错,逼你发现并改名,杜绝"被悄悄合并"。
• 否(就是要给第三方/全局类型扩展):用 interface + 声明合并——这是它的正当用武之地,刻意而为。
• 无论如何,给类型起带语境的、不易撞车的名字(加前缀、模块化、export),别用 Config Data 这种大路货当全局可见的 interface。

核心就一条:声明合并是 interface 为"扩展"准备的能力;不想被扩展、要封闭唯一的定义,就用 type;要扩展才刻意用 interface 合并——别让一个为扩展设计的特性,在你不想扩展时坑你。

第三件事:同一类"为开放扩展设计的机制,在你想要封闭唯一时反咬一口"的坑,我后来又撞见好几个

这次踩坑让我品出一个普遍的张力:很多机制是为"开放、可扩展、可被别处影响"而设计的,它带来灵活性的同时,也意味着"你的东西可以被别处悄悄改变/补充";当你其实想要的是"封闭、唯一、不受外界干扰"时,这种开放性就会变成"被意外影响"的隐患。这种坑不止声明合并:

• 猴子补丁 / 原型扩展:JS 里给内置原型(Array.prototype)加方法,本是为扩展,可多个库都这么干就互相覆盖、污染全局。
• CSS 全局样式覆盖:全局选择器本为统一风格,可不小心就跨组件互相覆盖,你的样式被别处的全局规则改了。
• 全局命名空间/变量:挂在全局上是为了到处可用,代价是任何人都能读写、覆盖,撞名就互相踩。
• 可被 override 的配置/方法:为灵活留了覆盖点,可被意外覆盖后行为就和你以为的不一样了。
• 开放继承的类:为复用而允许被继承重写,子类一重写就可能改变你没预期的行为。

它们的内核是同一个:"开放扩展"和"封闭唯一"是一对此消彼长的取向——开放带来可被扩展、可被影响的灵活,代价是失去了"这东西只由我说了算、不会被别处改变"的确定性;一个为开放而设计的机制,默认假设你欢迎外界的介入(合并、覆盖、扩展),可如果你真实的意图是封闭(这就是我的、唯一的、别人别碰),用了开放的机制,就等于把门敞开着、却以为它锁着。所以,选择一个机制前要先问清自己的意图:我要的是"开放可扩展"还是"封闭唯一"?然后选与意图匹配的机制(开放用 interface/继承/全局,封闭用 type/final/模块私有),别用一个开放的机制去承载一个封闭的意图。我把这套判断画成了一张图(见后文)。

第四件事:interface vs type——一张对照表

这次事故逼我把 interface 和 type 的关键差别摆成一张表,以后定类型前先按意图选:

看清这张表,选型就有了准绳:要"封闭、唯一、不被别处插手"的业务类型,优先 type(重名直接报错、杜绝意外合并);要"开放扩展"(给第三方/全局打补丁)才用 interface 并刻意利用声明合并。不是 interface 不好,而是它的"开放"要用在你真的想开放的地方。

第五件事:我曾经对 interface 想当然的几个误区

这场"interface 凭空多字段"的事故,把我对 interface 的一堆想当然照得清清楚楚:

这些误区的根子是同一个:我默认"定义一个 interface"就是"声明一个封闭的、唯一归我所有的类型",完全没意识到 interface 天生是开放可扩展的——它欢迎别处用同名声明来给它添砖加瓦,这是它的特性而非 bug。正因为我把一个开放的东西,当成了封闭的来用,我才会对"它被别处悄悄合并了字段"如此错愕。把一个为"开放扩展"而设计、欢迎外界介入的东西,当成"封闭唯一、只归我管"的来用,是这类"被意外扩展/影响"问题的共同根源。

第六件事:定类型、排查"类型莫名多/少字段"时,我现在的自检习惯

现在每当我定一个类型、或排查"interface 凭空多出/缺少字段",我都会先问"我要的是封闭唯一还是开放可扩展"。先看清 interface 声明合并为什么会悄悄混入字段:

然后用这张自检图按意图选 interface 还是 type:

配套地,我把"封闭类型用 type、有意扩展才用 interface 合并"固化成了团队约定,并示范正当的扩展用法:

// 约定 1:业务领域类型默认用 type(封闭、重名即报错、不被悄悄合并)
type OrderConfig = { name: string; timeout: number; };

// 约定 2:只有"有意扩展第三方/全局类型"时才用 interface 声明合并(刻意而为)
import 'express';
declare module 'express' {
  interface Request { traceId?: string; }   // 正当用途:给 Request 加字段
}

// 约定 3:排查"类型被合并"——全局搜同名声明
//   grep -rn "interface AppConfig" src/   看是不是多处同名被合并了

这套习惯的精髓,是"定类型先问封闭还是开放、封闭用 type 开放才用 interface、类型莫名多少字段先搜同名 interface 是否被合并"。它让我从"interface 就是我写的那几个字段"的想当然,变成了"分清封闭与开放、按意图选类型"——核心始终是:TypeScript 的 interface 有声明合并 declaration merging 特性——当遇到多个同名的 interface(以及 namespace 等)声明时它不会报重复定义的错而是把它们的成员自动合并到一个 interface 里,无论这些同名声明写在哪个文件哪个角落它们的字段都会被汇总到一个类型里;这个特性是有意设计的极有用的扩展机制——它让你能给一个无法修改源码的类型打补丁(给第三方库的 interface 加字段、给全局 Window 加自定义属性、给 Express 的 Request 挂你的字段),只要在自己代码里写一个同名 interface 把要加的字段写进去 TS 就会合并进去;但这个开放扩展的能力有另一面——正因为同名即合并、两个本来意图不同只是恰好重名的 interface 也会被毫无征兆地合并到一起、TS 不会报重名冲突来提醒你而是默默把它们揉成一个、导致你的接口凭空多出别处的字段;对照之下 type 类型别名不参与声明合并、重名直接报 Duplicate identifier 冲突;所以正解是分清你要的是一个不容别人插手的封闭定义还是一个欢迎扩展的开放定义——绝大多数业务类型用 type(它不参与声明合并、重名直接冲突报错逼你发现并改名、杜绝被悄悄合并)、只有确实要扩展第三方或全局类型时才有意地用 interface 加声明合并、并给类型起带语境不易撞车的名字(加前缀、模块化 export、放命名空间)别用 Config Data 这种大路货当全局可见的 interface;更一般地很多机制是为开放可扩展可被别处影响而设计的(interface 声明合并、原型扩展猴子补丁、全局 CSS、全局变量命名空间、可被 override 的配置方法、开放继承的类),它们带来灵活性的同时也意味着你的东西可以被别处悄悄改变或补充、当你真实意图其实是封闭唯一不受外界干扰时这种开放性就变成被意外影响的隐患——开放和封闭是一对此消彼长的取向、开放带来可被扩展的灵活代价是失去这东西只由我说了算不会被别处改变的确定性、一个为开放设计的机制默认假设你欢迎外界介入、所以选机制前要先问清自己的意图是要开放可扩展还是封闭唯一然后选与意图匹配的机制(开放用 interface 继承全局、封闭用 type final 模块私有)别用一个开放的机制去承载一个封闭的意图把门敞开着却以为它锁着。

我立下的几条规矩

这场"interface 凭空多字段"的事故,换来了我定 TS 类型时,刻进骨子里的几条铁律:

1. 同名 interface 会声明合并(成员揉一起),不报重名冲突。
2. 声明合并是为扩展第三方/全局类型设计的好能力,刻意才用。
3. 不想被别处插手的封闭业务类型,默认用 type(重名直接报错)。
4. 确实要扩展第三方/全局类型,才用 interface + 声明合并。
5. 类型起带语境不易撞的名字、模块化 export,降低撞名合并。
6. 类型莫名多/少字段,先全局搜有没有同名 interface 被合并。
7. 通用:开放机制别承载封闭意图,按"开放/封闭"意图选机制。

附:一段 interface 声明合并 vs type 的对照与排查

最后留一段我自己分清 interface 与 type、排查"类型被合并"时照着用的清单:

// ❌ 隐患:同名 interface 被声明合并, 意图不同也悄悄揉成一个
// a.ts
interface AppConfig { name: string; timeout: number; }
// b.ts (别处, 撞名)
interface AppConfig { retries: number; }
// 结果: AppConfig = { name; timeout; retries }  —— 不报错, 凭空多字段

// ✅ 封闭业务类型用 type: 重名直接冲突报错, 杜绝意外合并
type AppConfig = { name: string; timeout: number; };
// 别处再 type AppConfig = {...}  -> Duplicate identifier 'AppConfig' (报错!)

// ✅ 确需扩展第三方/全局类型, 才有意用 interface 声明合并(正当用途)
declare module 'express' {
  interface Request { traceId?: string; }   // 给 Request 加字段
}

/* 排查"类型莫名多/少字段"的办法:
 * 1. 全局搜同名声明:  grep -rn "interface AppConfig" src/
 *    出现多处 -> 它们被合并了, 这就是凭空多字段的来源
 * 2. 把可疑 interface 改成 type 试编译: 若报 Duplicate identifier
 *    -> 确实有同名声明在合并, 改名隔离或合并到一处
 */

这段清单的核心就一句:封闭、只归自己管的业务类型用 type(重名冲突报错);要扩展第三方/全局才用 interface 声明合并;类型莫名多/少字段先全局搜同名 interface 是否被合并。把"随手 interface"换成"按意图选 type 还是 interface",那"凭空多出别处字段"的怪事就不会再发生了。

写在最后

回头看,这场由"interface 声明合并"引发的"类型凭空多字段"事故,真正教给我的,远不止"封闭类型用 type"这一个技巧。它让我对"一个东西'可以被别处扩展、被别处影响'的能力,既是它最强大的优点,也是它最危险的陷阱;同一个特性,在你想要开放时是恩赐,在你想要封闭时是灾难",有了一次刻骨的体会。我栽跟头,是因为我把"定义一个 interface"理所当然地当成了"圈出一块只属于我的、封闭的领地"——在我的想象里,我写下 interface AppConfig,就等于宣告"这个类型是我的,就这几个字段,别人无权置喙";可 interface 的本性恰恰相反:它是一扇永远敞开的门,它的设计哲学就是"欢迎任何人用同名声明进来给我添东西"——这种"开放"是 TS 类型系统最引以为傲的扩展能力;我没意识到这一点,把一扇敞开的门当成了上了锁的保险柜,于是当别处一个同名 interface "大摇大摆走进来"、把它的字段添进我的类型时,我还在纳闷"我的保险柜怎么多了别人的东西"。这让我领悟到一个关于"开放与封闭"的深刻认知:软件世界里的每一个构造(类型、类、变量、样式、配置),在"能否被外界扩展/影响"这件事上,都隐含地站在一个从"完全开放"到"完全封闭"的光谱上的某个位置;"开放"意味着灵活、可扩展、可被复用和增强,但代价是你失去了对它的独占控制——别人可以介入、可以改变它;"封闭"意味着确定、唯一、不受干扰,但代价是牺牲了可扩展性;这两者没有绝对的优劣,关键在于它和你的意图匹不匹配:当你想要"留个口子让人扩展"时,开放是恩赐;当你想要"这就是我的、唯一的、谁也别动"时,你需要的是封闭,此时用了一个开放的构造,就等于把你以为锁着的东西其实敞开着,任由外界悄悄改变它而你浑然不觉;所以,选用任何一个构造之前,我都要先明确自己的意图是"开放"还是"封闭",再去选一个其开放/封闭性与意图相符的构造——而不是抓起一个顺手的,默认它的开放/封闭性恰好是我想要的。这给了我一种面对"一切'定义一个会被别处用到的东西'之事"时的清醒:每当我定义一个东西,我都会问"我希望它是开放给别处扩展影响的,还是封闭只归我独占的?我选的这个构造(interface/type、可继承/final、全局/私有),它的开放性和我的意图一致吗?会不会我以为锁着、其实敞着"——先明确开放还是封闭的意图、再选开放性与之匹配的构造;"分清开放与封闭的意图、别用开放机制承载封闭意图",是用对 interface 与 type、也是恰当设计一切构造可见性与可扩展性的关键。认清 interface 同名会声明合并、封闭类型用 type、按开放/封闭意图选构造——这,是我用一次"interface 凭空多出别处的字段"的事故,换来的、关于 TypeScript、也关于如何在开放与封闭间按意图取舍的、最朴素也最深刻的领悟。如果这篇复盘,能让你下次定一个只想归自己管的业务类型时,顺手写成 type 而不是 interface,那我对着那个"凭空多了 retries"的报错抓的那阵狂,就值了。

—— 别看了 · 2026