Next.js按需SSG构建动态路由页未生成完整HTML问题

核心诱因 #

按出现概率从高到低排序：

• JSX语法错误直接中断渲染：组件代码里存在标签闭合错误，段落标签写为<p ...>Some text/p>，斜杠位置错误导致标签没有正确闭合，React在SSG渲染阶段解析JSX树失败，直接终止组件渲染流程。而getStaticProps是独立于组件渲染的数据层逻辑，不受组件语法错误影响，所以接口返回的metadata能正常写入__NEXT_DATA__脚本块，但DOM节点完全无法生成。
• 自定义App/Document存在服务端不兼容逻辑：如果项目自定义了_app.tsx或_document.tsx，存在判断window对象才渲染子组件、初始状态直接返回null的兜底逻辑，会导致Node环境下的构建渲染阶段直接输出空根节点。
• Next.js 12.1.0版本原生Bug：该版本存在多个动态路由SSG渲染的已知问题，特定场景下会出现数据注入正常但DOM不输出的情况，后续12.x补丁版本已修复。
• next/image组件加载异常中断渲染：代码中引用的/assets/logo.svg如果没有存放在public目录对应路径，或者图片loader配置错误，12版本的Image组件在SSG阶段抛出未捕获错误时，也会导致渲染中断只保留数据块。

修复步骤 #

按顺序排查即可：

1. 首先修正JSX标签语法错误，把错误的p标签改为正确闭合格式：

// 错误写法
<p className="mb-[35px] text-white w-[90vw] text-[14px] md:w-[38vw] text-center md:text-[17px] font-normal leading-9">Some text/p>
// 正确写法
<p className="mb-[35px] text-white w-[90vw] text-[14px] md:w-[38vw] text-center md:text-[17px] font-normal leading-9">Some text</p>

2. 检查_app.tsx根组件逻辑，移除所有服务端渲染阶段会返回空节点的判断，不要在Node环境执行路径下返回null/空标签。
3. 校验静态资源路径：确认/assets/logo.svg实际存放位置为public/assets/logo.svg，构建阶段可正常读取，不会触发Image组件的资源加载错误。
4. 临时将getStaticPaths的fallback参数改为false，仅保留预生成的postId路径重新构建，排除阻塞式fallback按需生成阶段的缓存异常。
5. 以上操作无效时，将Next.js升级至12.x系列最终稳定版v12.3.4，规避12.1.0版本的原生SSG Bug。

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