路由已经删除,TypeScript 却还在寻找旧文件。重新生成类型也没有消除报错。这类问题容易被误判成业务代码没有改干净,实际参与检查的可能还有上一次开发会话留下的生成文件。
Next.js 于 UTC 2026 年 11 月 15 日 23:49 发布 16.5.0-canary.52,北京时间为 11 月 16 日 07:49。发布说明收录了修复 #100612,让 next typegen 和 next build 在适当条件下清理残留的开发态类型。该修复于 UTC 11 月 15 日合并,发布时间和合并时间均在本次写作的过去 48 小时内。
这是 canary 预发布中的变化,不能据此推断所有稳定版已经包含修复。本文依据上游说明、代码和测试分析,没有在这个 Hexo 博客中安装、升级或实测 Next.js。
背景:生成目录分开,不代表类型检查自然隔离
默认配置下,next dev 将自己的类型写入 .next/dev/types;next typegen 的输出通常在 .next/types。这次修改也纠正了 CLI 文档中容易混淆两者的表述。
目录分开解决了文件写到哪里的问题,却没有自动解决哪些文件会进入 TypeScript 检查。上游代码注释指出,项目的 tsconfig 会包含两套类型。开发服务器停止后,开发态生成文件不再随路由变化更新,但仍可能处于检查范围内。
例如,开发期间访问过 /before,生成的校验文件会引用对应页面和布局。停掉开发服务器,把路由移到 /after,再生成生产侧类型,旧的开发态校验文件仍可能引用已经不存在的路径,或者保留不再成立的路由约束。新类型生成正确,也不足以让旧类型自动失效。
这解释了为什么同一份源码在干净的 CI 中通过,在用过 next dev 的本地目录里却失败。这里描述的是问题机制,不是说所有本地与 CI 的差异都能归因于它。
核心修复:只清理已经失去维护者的类型
新增的 removeStaleDevTypes 处理的是配置目录下的 dev/types。next typegen 在生成类型后调用它,构建流程也在类型检查前接入清理。
直接删除这个目录并不安全。开发服务器可能仍在运行,它既需要这些类型,也会继续更新它们。实现因此复用了开发服务器的 dev/lock,先尝试拿锁,再决定是否删除。
| 当前状态 | 清理行为 | 需要避免的问题 |
|---|---|---|
没有 dev/types |
直接返回 | 不产生多余操作 |
| 开发服务器持有目录锁 | 保留类型 | 不删除正在维护的生成文件 |
| 可以取得目录锁 | 持锁删除 dev/types,随后释放 |
避免并发启动的开发服务器刚写完就被删 |
锁的作用不止是探测“开发服务器在不在”。清理期间继续持锁,才覆盖了检查之后、删除之前另一个进程启动的时间窗口。如果探测完马上释放,删除动作仍可能与新的生成动作交错。
不过,上游明确保留了限制。在禁用 lockDistDir 或使用 WASM bindings、无法获得真正锁保护的情况下,这仍是尽力清理,不能承诺同样的并发保证。清理遇到异常会输出警告,不直接让命令失败;残留类型引起的后续检查错误依然可能出现。
清理边界比“删一次 .next”更重要
修复只移除 dev/types,保留 .next/dev 中的其他内容,例如缓存和日志。下次启动开发服务器时,所需类型会重新生成。它没有把整个构建目录当成可随意丢弃的垃圾箱。
另一个容易漏掉的细节是自定义输出路径。上游针对 output: 'export' 搭配自定义 distDir 的场景增加了测试。在该场景中,构建产物可能进入 .next,开发态类型却位于配置的 <distDir>/dev/types。因此,清理路径需要从配置中的目录根定位,不能只盯着本次构建的实际输出目录。
这对维护内部脚本也有启示。若项目自定义了目录,先确认文件由谁生成、由哪项配置决定路径,再设计清理动作。硬编码 .next/dev/types 的脚本即使在默认项目中有效,也不能直接推广到所有配置。
回归测试验证了什么
上游新增或扩展的测试没有只验证“目录消失”,而是沿着实际开发操作检查结果。
删除路由的测试先启动开发服务器并访问页面,确认校验文件确实引用旧路径;停服、删除页面后再构建。它同时覆盖 TypeScript API 与 CLI 检查路径。CLI 相关测试还确认类型目录被移除,但开发目录本身仍然存在。
路由移动的测试把 /before 改为 /after,运行 next typegen 后再执行 tsc --noEmit,检查旧路径引用以及相关类型错误是否消失。此外,测试还覆盖开发服务器运行时执行类型生成或构建,要求其正在使用的开发态类型保持完整。
这些用例给出了修复目标和保护范围,但不等于所有操作系统、WASM 环境以及并发交错都已经得到穷尽验证。本文也不据此提出构建速度提升的结论,这项修复关注的是生成状态与检查结果的正确性。
实践启示:把生成文件纳入排错链路
遇到“源码里已经没有这个路由,检查却还引用它”的问题,可以先查看报错指向的是源码还是生成文件,再核对本地使用的 Next.js 版本、类型目录和 tsconfig 的包含范围。不要一开始就通过忽略类型错误掩盖症状。
如果需要验证修复,适合在独立分支或临时测试项目中固定版本,复现“启动开发服务、访问旧路由、停服、移动或删除路由、生成类型、执行检查”的完整过程。随后再验证开发服务仍运行时的行为,以及项目实际使用的自定义目录配置。以上是建议的验收步骤,不是本博客已经执行的测试结果。
对生产项目,不建议仅因这一条修复就直接追随最新 canary。先确认故障是否匹配,再评估预发布版本的其他变化;采用稳定版本时,也应核对相应发布说明或代码,而不是只比较版本号大小。
结语
构建工具的生成文件既是输出,也可能成为下一次检查的输入。只要它们跨开发会话存活,就需要明确的更新和清理规则。
这次 Next.js 修复把规则落到了具体位置:停止维护的开发态类型可以清理,运行中服务的类型需要保留,并用同一把目录锁协调两者。排查类似问题时,除了问“源码改对了吗”,也要看看检查器究竟读进了哪些旧文件。
参考来源
- Next.js 16.5.0-canary.52 发布说明,UTC 2026 年 11 月 15 日发布,收录 #100612。
- 上游修复 #100612:Remove stale .next/dev/types in next typegen and next build,包含设计说明、适用范围和验证限制。
- 修复代码、CLI 文档与回归测试差异,用于核对清理目录、锁保护、自定义 distDir 及运行中开发服务器的行为。