TypeScript项目声明文件中如何用类型别名和接口定义全局可用类型？

问题1：声明全局可用类型的正确写法 #

你目前写的declare module "AgendaTypes"属于模块类型声明，默认需要导入后才能使用，自然需要通过点语法访问内部接口。如果要实现和HTMLTextAreaElement一样无需导入、全局可用的效果，不需要包裹declare module，直接在.d.ts文件顶层写接口/类型别名即可，注意不要加export关键字——加了export后该文件会被识别为独立模块，内部类型会变为模块私有，必须导入才能使用。

正确的全局类型声明示例：

// App/src/@types/index.d.ts
// 直接写在顶层，全局可用
interface IAgendaItem {
    headline: string;
    children: IAgendaItem[];
    meetingNote: string;
}

type AgendaStatus = 'draft' | 'published' | 'archived';

如果担心全局命名冲突，也可以用全局命名空间分组，同样不需要导入：

declare namespace AgendaTypes {
    interface IAgendaItem {
        headline: string;
        children: IAgendaItem[];
        meetingNote: string;
    }
    type AgendaStatus = 'draft' | 'published' | 'archived';
}
// 用的时候直接写 AgendaTypes.IAgendaItem 即可，无需导入

lib.dom.d.ts里的DOM类型都是这种全局无export的声明逻辑，所以不需要导入就可以直接使用。

问题2：源码类型识别配置与跨项目类型共享 #

本地类型识别配置 #

要让源码识别全局类型，需要在各子目录的tsconfig.json中把对应的.d.ts文件纳入编译范围，同时修正typeRoots配置（默认只识别node_modules/@types下的类型）：

{
  "include": [
    "./**/*.ts",
    "./@types/**/*.d.ts",
    // 如果要引用App根目录的全局类型，要加上根目录@types路径
    "../@types/**/*.d.ts"
  ],
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./@types", "../@types"]
  }
}

App与Lib的类型共享 #

如果Lib的类型需要给App使用，两种常用方案：

• 本地monorepo场景：把Lib的@types/index.d.ts路径加到App各tsconfig的include和typeRoots配置中，即可全局识别Lib的类型
• Lib要发布为独立包的场景：在Lib的源码中正常导出类型，App安装Lib包后直接导入使用即可。

问题3：全局变量的存放规则 #

分两种场景处理：

• 仅做类型声明的全局变量：比如挂载在window上的运行时全局变量，统一放到.d.ts中做全局声明即可，不需要写实际赋值逻辑：

  // 全局.d.ts
  declare var globalAgendaConfig: {
    enableDraftSave: boolean;
    maxItemCount: number;
  };
  // 挂载在window上的变量扩展Window接口即可
  interface Window {
    globalAgendaConfig: {
      enableDraftSave: boolean;
      maxItemCount: number;
    }
  }
  

• 需要实际初始化赋值的全局变量：统一放到单独的global.ts文件中写赋值逻辑，同时把对应的类型声明放到.d.ts中，或者直接在global.ts中导出变量，其他文件导入使用，避免全局污染。

composite项目引用无法导入Lib代码的解决方案 #

首先排查基础配置错误：你目录中标注的ThingCreator、ThingUser下的配置文件后缀写的是tsconfig.ts，正确后缀必须是tsconfig.json，后缀错误会导致TS无法识别配置。
之后检查以下配置项：

1. Lib的tsconfig.json必须开启declaration: true，才能生成.d.ts类型文件供外部引用
2. App根目录的tsconfig.json中references路径要正确指向Lib的tsconfig所在位置，示例：

   {
     "references": [
       { "path": "../Lib" } // 直接写Lib的tsconfig所在目录，或者完整路径../Lib/tsconfig.json
     ]
   }
   

3. 导入Lib代码的路径要正确，如果没有配置路径别名，要写完整相对路径，比如import { myLibFunc } from '../../Lib/src/myLib'
4. 所有子项目的compilerOptions.rootDir要明确配置，避免编译输出的目录结构混乱导致引用失败。

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