Next.js随机报错“Cannot read properties of undefined (reading 'map')”求助

触发原因 #

这是Next.js开发模式下的典型缓存损坏问题，触发场景主要有三类：

• 本地.next缓存目录结构损坏：Next.js开发模式会将编译产物、路由映射、依赖预构建结果全部存在项目根目录的.next文件夹中，设备休眠、开发进程意外中断、跨Git提交切换后旧缓存与新代码不兼容，都会导致缓存结构损坏，触发启动报错。
• 依赖版本不匹配：如果本地node_modules安装的依赖版本，和package-lock.json/yarn.lock中锁死的版本不一致，结合Next.js的依赖预构建缓存机制，也会引发这类随机启动异常。
• Git缓存污染：如果项目的.gitignore规则未排除.next目录，该缓存目录会被提交到远端仓库，每次拉取代码时远端的环境不兼容缓存会覆盖本地缓存，直接导致启动失败，这也符合你删除本地仓库重拉后恢复正常的现象——重拉后首次启动会重新生成适配本地环境的全新.next缓存，因此不会报错。

修复方案 #

不需要每次删除整个本地仓库，按以下步骤操作即可快速恢复：

1. 停止运行中的开发服务，删除项目根目录的.next缓存目录，类Unix系统可执行命令：rm -rf .next，Windows系统可直接在资源管理器中删除该文件夹
2. 如果删除.next后仍报错，可进一步删除node_modules目录和对应的依赖锁文件，重新执行npm install安装依赖
3. 检查项目根目录的.gitignore文件，确认已添加.next规则，避免本地缓存被提交到远端仓库，从根源避免缓存污染问题
4. 可在package.json中添加快速清理脚本，后续出现同类问题直接执行对应命令即可：

{
  "scripts": {
    "clean": "rm -rf .next node_modules package-lock.json",
    "dev:fresh": "npm run clean && npm install && npm run dev"
  }
}

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