TypeScript中include包含类型文件无效，files配置正常的原因？

我在TypeScript项目里尝试扩展Express的Request类型，添加自定义属性，对应的类型文件src/types/index.d.ts内容如下：

declare module 'express-serve-static-core' {
  interface Request {
    customFlag?: boolean;
  }
}

我的tsconfig.json部分配置为：

"include": [
    "src/**/*.ts",
    "./server.ts"
],

运行项目时，使用req.customFlag会报错，提示该属性不存在于Request类型。但执行tsc --listFiles --noEmit时，能看到这个类型文件被列出。

当我修改tsconfig.json，添加files配置指定该类型文件后：

"include": [
    "src/**/*.ts",
    "./server.ts"
],
"files": [
    "src/types/index.d.ts"
],

项目就能正常运行了。我原以为include和files只是匹配模式不同，为什么include配置不生效？

原因分析 #

这是TypeScript处理**环境声明文件（.d.ts）**的逻辑差异导致的：

• 使用include时，TypeScript会按照文件的依赖关系加载文件。如果业务代码（比如server.ts）没有直接或间接导入这个类型文件，TypeScript可能会延迟处理它，导致检查业务代码类型时，Express的Request类型还没完成扩展。
• files配置是强制TypeScript把指定文件作为入口文件加载，不管有没有其他文件依赖它。这会让环境声明文件被优先处理，确保Request类型的扩展在业务代码类型检查前完成。

另外，tsc --listFiles显示文件被包含，只说明它进入了编译范围，不代表它的类型合并逻辑已经在业务代码检查前执行。

解决方案 #

除了用files指定类型文件，还有两种更优雅的处理方式：

1. 手动导入类型文件
   在使用req.customFlag的业务文件（比如server.ts）顶部添加导入：

import '../types/index.d.ts';

这会让TypeScript明确加载该类型文件，确保类型合并生效。

2. 配置typeRoots或types
   在tsconfig.json的compilerOptions中添加配置，让TypeScript自动加载指定的环境声明：

"compilerOptions": {
  "typeRoots": ["./src/types", "./node_modules/@types"]
}

或者直接指定要加载的类型文件：

"compilerOptions": {
  "types": ["src/types/index"]
}

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