TypeScript项目index.d.ts全局声明不被识别的问题咨询

1. 为何index.d.ts中的全局声明不被识别？ #

当项目里同时存在index.ts和index.d.ts时，TypeScript会默认把index.d.ts当成**index.ts的专属模块类型声明文件**，而非独立的全局类型文件。这时文件内的declare global块作用域会被绑定到index.ts模块内部，其他模块无法识别到这些全局类型扩展。

2. 文件名index.d.ts是否会影响TypeScript对全局类型的识别？ #

是的，index.d.ts这个文件名会触发TypeScript的特殊解析逻辑：同名的.ts和.d.ts文件会被自动配对，index.d.ts会被当作对应index.ts的类型补充文件，作用域和该模块绑定，而非全局作用域。只有当没有同名的.ts文件时，index.d.ts才会被当作普通全局类型文件处理。

3. 如何修复该问题，使index.d.ts中的全局类型被正确识别？ #

提供三种可行方案：

• 方案一：用tsconfig的files数组指定优先级
  在tsconfig.json里通过files数组明确列出index.d.ts，让TypeScript优先将其作为全局类型解析，而非模块配对文件：

  {
    "compilerOptions": {
      // 你的其他编译配置
    },
    "files": [
      "./index.d.ts"
    ],
    "include": [
      // 原有的include内容
    ]
  }
  

• 方案二：把全局类型文件移到专属目录
  创建@types或types目录，将index.d.ts移入其中，然后在tsconfig.json里配置typeRoots指向这个目录，让TypeScript识别它为全局类型文件：

  {
    "compilerOptions": {
      "typeRoots": ["./node_modules/@types", "./@types"],
      // 其他配置
    }
  }
  

• 方案三：给全局类型加模块标识并导入
  不改动文件名的情况下，给index.d.ts添加模块声明，避免和index.ts配对：

  declare module "app-global-types" {
    declare global {
      namespace Express {
        interface Request {
          user_id?: number;
          role?: string;
        }
      }
    }
  }
  
  export {};
  

  然后在项目入口文件（比如index.ts）里导入这个模块：

  import "app-global-types";
  

内容的提问来源于stack exchange，提问作者Naga mani kanta manam