Next.js含Cypress多tsconfig下如何实现分文件夹类型检查

问题根因 #

报错的来源非常直接：

• 根目录tsconfig.json的include配置**/*.ts会递归扫描全量子目录，把cypress下的TS文件也纳入了根配置的检查范围
• 根配置没有加载Cypress对应的类型声明，校验这些文件时就会报类型缺失错误
• 当前type-check脚本仅执行了一次根目录tsc检查，完全没有触发cypress目录独立tsconfig的校验流程

方案1：最低改造成本 #

第一步：缩小根配置的扫描范围 #

修改根目录tsconfig.json的exclude字段，把cypress目录排除出去：

"exclude": ["node_modules", "cypress"]

修改后，根配置的tsc执行时不会再处理cypress目录下的任何文件。

第二步：调整类型检查脚本 #

用tsc的--project（简写-p）参数分别指定两个目录的tsconfig路径，串联执行检查，修改package.json脚本配置：

"type-check": "tsc --pretty --noEmit -p ./tsconfig.json && tsc --pretty --noEmit -p ./cypress/tsconfig.json"

参数说明：-p会跳过当前目录的默认tsconfig查找逻辑，直接使用指定路径下的配置执行校验；两个流程用&&串联，任意一步校验报错就会终止脚本输出非零退出码，适配CI/CD的校验规则。

方案2：基于TypeScript项目引用的规范配置 #

适合多独立配置的长期维护项目，不需要手动串联多条tsc命令：

第一步：同样先缩小根配置扫描范围 #

和方案1一致，把cypress加入根tsconfig的exclude列表：

"exclude": ["node_modules", "cypress"]

第二步：关联cypress的独立项目配置 #

在根目录tsconfig.json中增加项目引用配置，关联cypress目录的tsconfig：

{
  // 原有compilerOptions、include、exclude内容保持不变
  "references": [
    { "path": "./cypress" }
  ]
}

第三步：调整检查脚本 #

给tsc加上--build参数，自动按顺序检查所有关联的项目配置：

"type-check": "tsc --build --pretty"

说明：tsc --build模式会自动递归解析所有项目引用，逐个执行对应配置的类型检查；因为两个配置都已经设置了noEmit: true，所以流程不会生成JS编译产物，仅会生成用于增量校验的.tsbuildinfo缓存文件。后续如果新增其他独立tsconfig（比如测试目录、构建脚本目录），只需要在根tsconfig的references里加一条路径即可，不需要修改脚本逻辑。

常见误区提醒 #

• 不需要修改现有cypress/tsconfig.json的继承配置，它扩展根tsconfig的写法是完全正确的
• 两种方案都可以实现目标，小型项目选方案1改造成本最低，需要扩展多模块配置选方案2更便于长期维护
• 项目引用能力需要TypeScript 3.0以上版本支持，目前主流Next.js项目的TS版本都满足要求
• 如果使用方案2，建议把.tsbuildinfo文件加入项目的.gitignore，避免增量缓存文件被提交到代码仓库

内容的提问来源于stack exchange，提问作者J. Hesters