TypeScript 中无法通过声明合并为第三方类实例动态添加原型方法，需结合接口扩展类型与运行时挂载方法：先用 declare module 扩展 AxiosInstance 等类型，再直接为 axios 实例赋值 cache 方法，确保类型安全与运行时可用。
在 TypeScript 中，不能直接通过声明合并（Declaration Merging）为第三方类的实例动态添加原型方法——因为声明合并只影响类型系统（编译时），不改变运行时行为。但你可以结合 类型声明扩展 和 运行时原型补丁，安全地实现“既让 TS 知道新方法存在，又让 JS 运行时可用”的效果。
1. 用接口合并扩展实例类型
假设你用的是第三方库如 axios，它导出一个默认实例 axios，其类型是 AxiosInstance。你想给这个实例加一个 cache() 方法：
先通过接口声明合并，扩展 AxiosInstance 类型：
// axios.d.ts 或任意 .d.ts 文件中
import 'axios';
import axios, { AxiosInstance } from 'axios';
declare module 'axios' {
interface AxiosInstance {
cache(url: string, config?: any): Promise<any>;
}
}
这样 TypeScript 就会认为 axios.cache(...) 是合法调用，不会报错。
2. 在运行时挂载原型方法
类型有了，还得让方法真正可用。注意：不要修改 AxiosInstance.prototype（它不是构造函数，而是工厂返回的对象），而应直接给具体实例（如 axios 默认实例）挂方法：
- 推荐方式：直接赋值给实例对象（最安全、不影响其他实例）
- 不推荐：修改
AxiosInstance.prototype—— 因为AxiosInstance并非真实类，没有统一原型链
示例：
import axios from 'axios';
// 扩展默认实例
axios.cache = function (url, config = {}) {
return axios.get(url, { ...config, cache: true });
};
// 现在可以安全调用且有类型提示 ✅
axios.cache('/api/data').then(...);
3. 对自定义封装实例做类型+运行时双扩展
如果你自己创建了 const api = axios.create(...)，那就需要同时扩展类型和实例：
- 类型扩展：在
declare module 'axios'中，也可单独为api的类型做declare module或使用declare const+ 接口合并 - 更清晰的做法：定义专属接口并用
as断言或类型增强
例如：
// api.d.ts
import axios, { AxiosInstance } from 'axios';
export interface ExtendedAxiosInstance extends AxiosInstance {
cache(url: string, config?: any): Promise<any>;
}
// 创建时断言类型（或用 as ExtendedAxiosInstance）
const api = axios.create() as ExtendedAxiosInstance;
api.cache = function (url, config) {
return this.get(url, { ...config, cache: true });
};
4. 注意事项与避坑点
- 声明合并仅作用于类型检查，不生成任何 JS 代码；原型方法必须手动挂载，否则运行时报
undefined is not a function - 避免污染全局
any类型，不要用declare global随意扩展现有对象（如Object.prototype） - 若第三方库本身支持插件机制（如 axios 的 interceptor、request adapter），优先用官方扩展点，而非硬打补丁
- Vue、React 等框架实例（如
vm、Component）同理：用declare module扩展类型，再用app.config.globalProperties或defineComponent+setup注入方法
