如何修复TypeScript中“Invalid module name in augmentation”错误？

我在TypeScript中使用declare module创建了一个虚拟的foo-lib模块，但运行代码时出现如下错误：

Error: Invalid module name in augmentation. The module 'foo-lib' cannot be found. (Error code: 2664)

对应的代码片段：

declare module 'foo-lib' {
  export namespace FooLib {
    interface Foo {
      prop: boolean;
    }
  }
}

import { Foo } from './foo-lib';

const a = {} as Foo;

错误原因 #

1. 模块增强语法误用：你写的declare module 'foo-lib'属于TypeScript的模块增强语法，这种语法要求目标模块foo-lib必须真实存在（要么是已安装的npm包，要么是项目里有同名文件），但当前项目中没有这个模块，所以TS抛出找不到模块的错误。
2. 导入路径与声明不匹配：你的导入语句是import { Foo } from './foo-lib'，指向本地相对路径的文件，但你声明的是全局模块'foo-lib'（不带相对路径），两者完全不对应。同时你也没创建./foo-lib这个本地文件，进一步触发错误。

修复方案 #

根据实际需求分两种情况处理：

情况1：定义完全虚拟的第三方模块 #

如果只是模拟不存在的第三方库类型，调整声明的导出结构，并保证导入路径和模块名一致：

declare module 'foo-lib' {
  // 直接导出Foo接口，无需嵌套多余命名空间
  export interface Foo {
    prop: boolean;
  }
}

// 导入模块名要和declare的完全一致
import { Foo } from 'foo-lib';

const a = {} as Foo;

情况2：给本地./foo-lib文件补充类型 #

如果项目里确实有./foo-lib.ts/./foo-lib.js文件，需要补充类型声明：

// 模块声明路径和导入路径保持一致
declare module './foo-lib' {
  export interface Foo {
    prop: boolean;
  }
}

// 导入本地模块
import { Foo } from './foo-lib';

const a = {} as Foo;

也可以把这个类型声明单独放在foo-lib.d.ts文件中，TypeScript会自动识别并关联到同名的本地模块。

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