在 TypeScript 项目里，我们经常会定义一些业务领域的自定义类型，例如用户、订单或商品。当这些类型的数组需要频繁做某些特定计算时，如果每次都写一遍循环或 filter，代码会变得零散且容易出错。很多团队希望像使用原生数组方法那样，直接在高亮类型数组上调用语义清晰的自定义函数，同时还能享受完整的类型提示。
为什么不能直接修改 Array.prototype
在 JavaScript 中，往 Array.prototype 上挂载方法是最直接的数组扩展方式，但在 TypeScript 与大型项目中这会引发明显问题。首先，原型扩展是全局性的，任何数组都会拥有该方法，而实际上你的函数可能只适用于某种结构。其次，TypeScript 无法自动感知你运行时加上的方法，必须额外写声明，否则调用处会报类型错误。
更为隐蔽的风险是命名冲突与可维护性下降。如果多个库都扩展了同名方法但行为不同，调试将极其困难。此外，原型污染会让单元测试不够纯粹，并且在服务端渲染或同构代码中可能引发不一致。因此，针对自定义类型数组，我们应当使用类型安全的局部扩展方案。
原型扩展的示例代码与问题
下面这段代码在运行时可用，但类型系统并不认可：
interface User {
id: number;
age: number;
}
// 运行时扩展，但 TS 不知道
Array.prototype.sumAge = function (this: User[]) {
return this.reduce((s, u) => s + u.age, 0);
};
const users: User[] = [{ id: 1, age: 20 }, { id: 2, age: 30 }];
// 下面这行在 TS 中会报错：Property 'sumAge' does not exist
console.log(users.sumAge());
从上面的例子可以看出，单纯运行时的扩展无法融入 TypeScript 的类型世界。即便通过强制类型断言绕过检查，也失去了类型保护的意义，还可能让其他开发者误以为所有数组都能调用 sumAge。
使用声明合并为特定数组添加方法
TypeScript 支持对全局接口进行声明合并。我们可以针对 Array 接口做泛型约束的合并，使得只有特定元素类型的数组才拥有自定义函数。这种方式不会污染其他数组，并且类型推导完全正常。
具体做法是使用 declare global 或在模块文件中直接扩展 Array 接口。需要注意，扩展时应明确 this 的类型，并使用泛型参数限定元素结构。下面演示如何为 User 数组添加 sumAge 与 adults 两个方法。
声明合并实现类型安全扩展
interface User {
id: number;
age: number;
}
// 声明合并：仅当数组元素为 User 时存在这些方法
declare global {
interface Array<T> {
sumAge(this: User[]): number;
adults(this: User[]): User[];
}
}
if (!Array.prototype.sumAge) {
Array.prototype.sumAge = function (this: User[]) {
return this.reduce((s, u) => s + u.age, 0);
};
}
if (!Array.prototype.adults) {
Array.prototype.adults = function (this: User[]) {
return this.filter(u => u.age >= 18);
};
}
const users: User[] = [
{ id: 1, age: 15 },
{ id: 2, age: 25 }
];
console.log(users.sumAge()); // 40
console.log(users.adults()); // [{ id: 2, age: 25 }]
这种写法的优势在于调用处拥有完美的智能提示，且 TypeScript 会阻止在 number[] 上调用 sumAge。缺点是仍然改了原型，在极少数需要完全避免原型修改的场景中不够理想。另外，声明合并要求文件为模块或包含全局声明，否则可能不生效。
使用工具函数返回包装类型
如果不想触碰原型，可以定义一个工具函数，接收自定义类型数组并返回一个带有自定义方法的对象或子类实例。这样扩展是显式的，且更容易做 tree-shaking 与测试。
我们可以借助 Class 或闭包来实现。下面示例通过一个 UserList 类包装 User[]，在类内部提供领域方法，同时保持底层数组可访问。这种方式对 SSR 与纯函数风格更友好。
包装类方式示例
interface User {
id: number;
age: number;
}
class UserList {
constructor(private items: User[]) {}
get data(): User[] {
return this.items;
}
sumAge(): number {
return this.items.reduce((s, u) => s + u.age, 0);
}
adults(): User[] {
return this.items.filter(u => u.age >= 18);
}
}
const users = new UserList([
{ id: 1, age: 15 },
{ id: 2, age: 25 }
]);
console.log(users.sumAge());
console.log(users.adults());
包装类的缺点是调用前必须显式构造，不能像数组原生方法那样链式直接写。但它完全避免了全局副作用，也方便在方法内加入日志、缓存等横切逻辑。对于中大型项目，这种显式优于隐式的做法往往更可持续。
两种方案对比与选择建议
从类型安全、可维护性与入侵性三个维度来看，声明合并上手快、调用自然，适合内部工具库；包装类无副作用、易测试，适合对外 SDK 或复杂领域模型。如果团队统一规范，也可以组合使用：底层用包装类，上层通过类型别名提供语法糖。
无论选择哪种，都应在 d.ts 或模块顶部集中声明，避免散落在业务文件中。同时建议为自定义函数编写单元测试，确保数组扩展逻辑在重构时不被破坏。这样既能提升开发效率，也能保障 TypeScript 项目长期的类型健康。
| 方案 | 入侵性 | 类型提示 | 适用场景 |
|---|---|---|---|
| 声明合并原型 | 高 | 好 | 内部项目快速扩展 |
| 包装类 | 无 | 好 | 库、复杂领域 |
小结
为自定义类型数组扩展函数，核心目标是让领域操作聚合且类型安全。TypeScript 提供了声明合并与显式包装两条路径，前者贴近原生数组写法，后者更干净可控。理解它们的底层机制后，你可以根据项目规模与协作规范灵活选用，不必再依赖any或重复的工具函数。
TypeScript自定义类型数组扩展修改时间：2026-08-06 04:21:34