React应用中TypeScript嵌套模块导入报错的正确解决方案

报错根因 #

• 代码里使用的 import 别名 = 路径 是TypeScript为兼容AMD/CommonJS模块设计的旧语法，@babel/plugin-transform-typescript 默认不支持这类语法，会直接抛出运行时报错。
• 原有嵌套 declare module 的全局写法，没有对应物理模块路径，无法直接适配ES模块的导入语法规则。

符合规范的实现方案 #

方案1（推荐）：调整类型声明结构适配ES模块规范 #

修改类型声明文件apiTypes.d.ts的写法，不要用嵌套全局declare module的结构，改为直接导出命名空间：

// apiTypes.d.ts
export namespace ModuleA {
  export namespace ModuleB {
    export interface ModuleABInterface {
      // 正常定义接口属性即可
    }
  }
}

在业务文件token.ts里直接用标准ES模块语法导入，完全不需要旧的import =写法：

// token.ts
import { ModuleA } from './apiTypes';

// 直接引用嵌套的类型即可
let test: ModuleA.ModuleB.ModuleABInterface;

如果不需要跨文件共享类型，完全可以把嵌套类型写在全局命名空间下，不需要额外导入：

// apiTypes.d.ts 无顶层import/export语句时，会被识别为全局声明文件
declare namespace ModuleA {
  namespace ModuleB {
    interface ModuleABInterface {}
  }
}

这种写法下所有TS文件可以直接全局访问ModuleA.ModuleB.ModuleABInterface，不需要写任何导入语句。

方案2：兼容原有全局声明结构的写法 #

如果旧的类型声明结构无法修改，只要保证apiTypes.d.ts没有任何顶层import/export语句（即被TS识别为全局类型声明文件），就可以直接在业务代码里引用类型，省略import =语句：

// token.ts
// 全局声明的类型可以直接访问
let test: ModuleA.ModuleB.ModuleABInterface;

不推荐的临时兼容方案 #

如果实在无法修改原有业务代码，可以在Babel配置中开启对旧TS语法的支持，但这种方式会增加配置复杂度，提升长期维护成本，不建议在正式项目中使用：

// babel.config.js 配置片段
module.exports = {
  plugins: [
    ['@babel/plugin-transform-typescript', {
      allowDeclareFields: true,
    }],
  ]
}

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