Next.js 构建失败排查：从类型错误到 SSG 数据收集

类型错误（第一阶段挂）

Type error: ...——tsc 的输出会指明文件与行号。逐日 AI 内容站的高频类型错误：md frontmatter 的字段与接口不匹配（如 category 枚举外的新值）、union 类型的属性收窄问题（'minutes' in g 的写法在严格模式下收窄失败，改用显式类型）。修复后重跑 typecheck 再 build。

SSG 数据收集失败（第二阶段挂）

Failed to collect page data for /路由名——这个报错藏在 Next 的封装里，需要自己复现根因。逐日 AI 的排查路径：内容站的 md 文件 frontmatter 解析失败（用 node + gray-matter 遍历 content 目录逐个验证，注意脚本的工作目录必须在 apps/web 下——路径错了会静默跳过所有目录报 ALL OK）、generateStaticParams 的返回值格式、页面组件对 undefined 数据的处理（notFound 的兜底是否覆盖）。

环境变量缺失（第三阶段挂）

构建期读取的环境变量（如 NEXT_PUBLIC_ 开头的统计 ID）在 CI/服务器上没有配置——症状是"本地构建好好的，服务器构建挂"或"构建成功但页面数据为空"。处理：.env.local 与构建环境的环境清单对齐（逐日 AI 的清单见 .env.local 的注释模板）。

内存溢出（大站点构建挂）

页面数量大时构建进程可能 OOM（exit 无报错或 Killed）——处理：NODE_OPTIONS=--max-old-space-size=4096 提升构建内存；服务器上构建时先停掉其他吃内存的服务（dev server 运行中跑构建还会互相污染 .next 目录——构建前先停 dev，这条教训踩过多次）。

构建产物的验证

构建成功不等于部署成功：静态导出后抽检关键页面的 HTML 内容完整（标题/正文/统计代码）、sitemap 数量正确、404 页存在——三项过完再上线。