TypeScript类库扩展第三方库后，项目引用无法调用扩展方法怎么办？

你遇到的核心问题是：类库my-lib中对other-lib的ExistingClass进行的模块扩展，没有被消费端my-app的TypeScript类型系统识别到。这是因为扩展声明未被正确包含到my-lib最终发布的类型文件中。

解决步骤 #

1. 确保扩展声明被引入到类库入口 #

把扩展代码单独放在一个文件中（比如src/extensions/other-lib.ts），然后在my-lib的入口文件（如src/index.ts）中导入该文件——哪怕只是导入不使用，也能让tsup将其类型合并到最终的dist/index.d.ts里。

示例代码：

// src/extensions/other-lib.ts
declare module "other-lib" {
    interface ExistingClass {
        newFunction(): void;
    }
}

ExistingClass.prototype.newFunction = function() {
    console.log("Ok");
}

// src/index.ts
// 导出你类库的其他代码
export * from './your-core-code';
// 导入扩展文件，确保类型被包含到最终dts中
import './extensions/other-lib';

2. 检查tsup配置的类型生成逻辑 #

确保tsup配置里开启了dts选项，且入口包含了所有需要处理的文件：

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  dts: true, // 必须开启，生成合并后的类型文件
  format: ['cjs', 'esm'],
});

3. 验证最终类型文件是否包含扩展 #

构建my-lib后，打开dist/index.d.ts，确认其中存在对other-lib的扩展声明：

declare module "other-lib" {
    interface ExistingClass {
        newFunction(): void;
    }
}

如果没有，说明扩展文件未被正确引入到入口，需要检查导入路径是否正确。

4. 确认模块名称完全匹配 #

确保declare module "other-lib"中的模块名，和你项目中实际安装的other-lib包名完全一致（比如带scope的包要写成"@scope/other-lib"）。

原理说明 #

TypeScript的模块扩展（module augmentation）需要满足两个关键条件：

• 扩展声明必须处于模块上下文中（文件包含import/export，不是全局脚本）
• 该声明必须被TypeScript类型系统加载到——对于发布的类库，就是要被合并到package.json指定的types入口文件里

如果扩展文件未被入口导入，tsup生成类型文件时不会自动收录它，导致消费端无法识别扩展的方法。

内容的提问来源于stack exchange，提问作者stevancorre