JavaScript / TypeScript / 系统课时
文件范围配置
文件范围配置
一个 TypeScript 工程不一定要编译目录中的所有文件。通过 files、include 和 exclude,可以明确哪些文件作为编译入口被发现,并避免测试代码、生成文件或临时目录意外进入构建结果。
学习目标
- 使用
files精确指定参与编译的入口文件 - 使用
include和exclude按目录与通配模式控制文件发现范围 - 通过编译器命令验证最终进入程序的文件集合
files 适合明确的文件清单
files 接收文件路径数组,适合入口数量少且希望严格控制的工程。列出的文件会直接成为 TypeScript 程序的根文件,不需要再被 include 匹配。
例如,一个只有两个源码入口的小项目可以这样配置:
{
"compilerOptions": {
"strict": true,
"noEmit": true
},
"files": [
"src/main.ts",
"src/config.ts"
]
}这类配置的优点是范围非常明确,但每增加一个独立入口都要修改 tsconfig.json。因此,大多数持续增长的源码目录更适合使用 include。
include 与 exclude 控制文件发现
include 用通配模式描述要扫描的文件,常见写法是 src/**/*.ts。exclude 则从 include 的搜索结果中排除目录或文件,适合测试目录、构建产物和临时文件。
下面的配置只主动发现 src 下的 TypeScript 文件,并跳过测试文件:
{
"compilerOptions": {
"strict": true,
"outDir": "dist"
},
"include": [
"src/**/*.ts"
],
"exclude": [
"src/**/*.test.ts",
"dist"
]
}files 与 include 可以同时存在,此时两者得到的根文件会共同参与编译。工程规模较大时,通常让 include 描述源码边界,再用 exclude 去除无需主动扫描的内容即可。
查看编译器实际纳入的文件
不要只凭目录结构判断配置是否生效,可以让 TypeScript 输出最终程序包含的文件。假设项目已经安装 TypeScript,并且存在前面的 tsconfig.json,执行:
npx tsc --noEmit --listFiles预期输出会先列出 TypeScript 标准库文件,再列出项目实际参与编译的源码,路径因安装位置而不同,例如:
<PATH>/node_modules/typescript/lib/lib.d.ts
<PATH>/src/config.ts
<PATH>/src/main.ts如果本应排除的测试文件出现在列表中,应检查它是否被其他源码导入,或者是否通过 files 被直接指定。若目标源码没有出现,则优先检查 include 模式是否覆盖了真实目录和文件扩展名。
选择配置方式
文件很少且集合固定时,files 最直接;源码按目录持续增加时,优先使用 include;exclude 则适合缩小 include 的扫描结果,而不应被当作安全边界或模块导入禁令。
工程配置的关键不是把三个字段全部写上,而是让根文件发现规则与项目目录职责一致,并用 --listFiles 验证编译器看到的结果。