CRA+Typescript项目如何实现支持扩展第三方类型的全局类型声明

问题根源 #

你遇到的全局声明失效不是isolatedModules配置导致的，是TypeScript的默认规则：只要.d.ts文件顶层存在import/export语句，TS会将该文件识别为普通模块，而非全局声明文件，内部的类型默认不会注入全局作用域。

解决方案 #

使用declare global语法包裹所有需要全局暴露的类型，同时添加空的export {}适配CRA的isolatedModules约束即可，完全不需要修改默认配置。

完整示例（src/global.d.ts）

// 顶部可正常导入第三方模块、项目内部模块的类型，推荐用import type避免引入无效代码依赖
import type { ExternalType } from 'some-public-module';
import type { AuthMachineContext } from './machine';

// 所有要全局生效的类型都放在declare global块内
declare global {
  // 场景1：扩展第三方类型的自定义接口
  interface MyType extends ExternalType {
    myCustomThing: string;
  }

  // 场景2：全局暴露从业务文件提取的类型
  type GlobalAuthContext = AuthMachineContext;

  // 其他普通全局类型也可以统一放在这里管理
  interface CommonResponse<T = unknown> {
    code: number;
    data: T;
    message: string;
  }
}

// 加空export适配模块规则，避免TS报错，不影响全局类型生效
export {};

效果验证 #

配置完成后，你在项目任意ts/tsx文件中，都可以直接使用MyType、GlobalAuthContext等自定义类型，无需手动导入，完全符合你提出的三个需求。

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