Next.js App Router开发中消除tsc --watch TS报错的方案

问题背景 #

用Create T3 App搭建的Next.js App Router项目，开发时通过concurrently同时运行npm run dev和tsc --watch，用来实时监测所有文件的TypeScript错误。这套配置在Page Router中正常工作，但切换到App Router后出现TS6053错误，提示找不到.next/types目录下的文件。手动删除tsconfig.json里include数组中的.next/types/**/*.ts能消除错误，但启动开发服务器时Next.js会自动重新添加该配置。本质原因是Next.js重建.next/types文件的时机晚于tsc启动编译，二者的竞态条件导致报错。

可行解决方案 #

方案1：给tsc监听加延迟启动

简单直接，让tsc延迟几秒再启动，给Next.js留出生成类型文件的时间。修改package.json的脚本配置：

"scripts": {
  "dev": "concurrently \"next dev\" \"npm run tsc-watch\"",
  "tsc-watch": "sleep 3 && tsc --watch"
}

Windows系统需将sleep 3替换为timeout /t 3 /nobreak。缺点是延迟时间无法精准匹配项目生成速度，大项目可能仍存在报错风险。

方案2：tsc命令行排除自动生成的类型文件

.next/types下的文件由Next.js自动维护，无需tsc检查。直接在tsc命令行中排除该目录，即可绕过Next.js自动添加的include配置。修改脚本：

"scripts": {
  "dev": "concurrently \"next dev\" \"tsc --watch --exclude '.next/types/**/*.ts'\""
}

命令行的--exclude参数会覆盖tsconfig.json中的include配置，tsc不再检查这些自动生成的文件，也就不会触发找不到文件的错误。

方案3：用工具监听文件生成后再启动tsc（最可靠）

使用wait-on工具监听.next/types目录，等该目录生成完成后再启动tsc --watch，从根源避免竞态问题。

1. 安装依赖：

npm install -D wait-on

2. 修改package.json脚本：

"scripts": {
  "dev": "concurrently \"npm run next-dev\" \"npm run tsc-watch\"",
  "next-dev": "next dev",
  "tsc-watch": "wait-on .next/types && tsc --watch"
}

如果需要跨平台兼容（同时支持Windows和Mac/Linux），可替换为cross-wait-on：

npm install -D cross-wait-on

然后将脚本中的wait-on替换为cross-wait-on即可。

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