JavaScript / TypeScript / 系统课时

文件范围配置

文件范围配置

一个 TypeScript 工程不一定要编译目录中的所有文件。通过 files、include 和 exclude,可以明确哪些文件作为编译入口被发现,并避免测试代码、生成文件或临时目录意外进入构建结果。

学习目标

  • 使用 files 精确指定参与编译的入口文件
  • 使用 include 和 exclude 按目录与通配模式控制文件发现范围
  • 通过编译器命令验证最终进入程序的文件集合

files 适合明确的文件清单

files 接收文件路径数组,适合入口数量少且希望严格控制的工程。列出的文件会直接成为 TypeScript 程序的根文件,不需要再被 include 匹配。

例如,一个只有两个源码入口的小项目可以这样配置:

json
{
  "compilerOptions": {
    "strict": true,
    "noEmit": true
  },
  "files": [
    "src/main.ts",
    "src/config.ts"
  ]
}

这类配置的优点是范围非常明确,但每增加一个独立入口都要修改 tsconfig.json。因此,大多数持续增长的源码目录更适合使用 include。

include 与 exclude 控制文件发现

include 用通配模式描述要扫描的文件,常见写法是 src/**/*.ts。exclude 则从 include 的搜索结果中排除目录或文件,适合测试目录、构建产物和临时文件。

下面的配置只主动发现 src 下的 TypeScript 文件,并跳过测试文件:

json
{
  "compilerOptions": {
    "strict": true,
    "outDir": "dist"
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": [
    "src/**/*.test.ts",
    "dist"
  ]
}

files 与 include 可以同时存在,此时两者得到的根文件会共同参与编译。工程规模较大时,通常让 include 描述源码边界,再用 exclude 去除无需主动扫描的内容即可。

查看编译器实际纳入的文件

不要只凭目录结构判断配置是否生效,可以让 TypeScript 输出最终程序包含的文件。假设项目已经安装 TypeScript,并且存在前面的 tsconfig.json,执行:

bash
npx tsc --noEmit --listFiles

预期输出会先列出 TypeScript 标准库文件,再列出项目实际参与编译的源码,路径因安装位置而不同,例如:

text
<PATH>/node_modules/typescript/lib/lib.d.ts
<PATH>/src/config.ts
<PATH>/src/main.ts

如果本应排除的测试文件出现在列表中,应检查它是否被其他源码导入,或者是否通过 files 被直接指定。若目标源码没有出现,则优先检查 include 模式是否覆盖了真实目录和文件扩展名。

选择配置方式

文件很少且集合固定时,files 最直接;源码按目录持续增加时,优先使用 include;exclude 则适合缩小 include 的扫描结果,而不应被当作安全边界或模块导入禁令。

工程配置的关键不是把三个字段全部写上,而是让根文件发现规则与项目目录职责一致,并用 --listFiles 验证编译器看到的结果。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

文件范围配置

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通