必须显式配置output: 'export'才能触发Next.js静态导出，否则即使使用getStaticProps也无法生成纯静态HTML；需禁用getServerSideProps、API路由和next/image优化，并避免_app.js中使用typeof window判断，且构建产物须通过HTTP服务预览。
next.config.js 中 output: 'export' 配置必须显式启用
Next.js 默认不生成纯静态 HTML，即使你用了 getStaticProps 和 getStaticPaths，构建产物仍是带服务端逻辑的 bundle。只有明确设置 output: 'export'，才能触发静态导出流程。
常见错误是只配了 output: 'export' 却漏掉其他配套项，导致构建失败或行为异常：
- 必须移除所有使用
getServerSideProps的页面——静态导出下它直接报错 -
fallback: true在动态路由中不可用，只能用fallback: false或fallback: 'blocking' - 若项目含 API 路由（
pages/api/），这些文件会被忽略，但路径不能残留依赖逻辑
Image 组件在静态环境下必须禁用优化
Next.js 的 next/image 默认依赖服务端图片优化 API，而静态导出后没有运行时服务，访问 /_next/image 会 404，图片直接不显示。
解决方式是在 next.config.js 中强制关闭优化：
立即学习“前端免费学习笔记（深入）”；
module.exports = {
output: 'export',
images: {
unoptimized: true,
},
}
这样 next/image 会退化为普通 <img> 标签，加载原始路径资源。注意：此时 src 必须指向真实存在的静态文件（如 public/images/logo.png），且路径需与最终部署结构一致。
详细的 Three.js 3D 图形参考，涵盖场景设置、相机、几何体、材质、光照、动画、控制器、加载器、数学工具和调试。
_app.js 中 typeof window !== "undefined" 会彻底破坏静态 HTML 生成
这是最隐蔽也最致命的问题：只要 _app.js 的 render() 方法里包裹了 typeof window !== "undefined" 判断，服务端渲染就会返回空内容——因为 Node 环境下 window 是 undefined，整个 JSX 表达式求值为 false。
结果就是：getStaticProps 数据被丢弃、View Page Source 看不到任何页面内容、SEO 抓取失败、禁 JS 后白屏。
修复方法极简：
- 删掉所有
typeof window !== "undefined"包裹的 JSX 片段 - 把客户端专属逻辑（如
useEffect、事件监听）移到页面组件内部，而非_app.js - 需要条件渲染时，用
useEffect+useState延迟到客户端执行
静态资源路径和本地预览必须走 HTTP 服务
生成的 out 目录不能直接双击打开 HTML 文件——浏览器用 file:// 协议加载时，相对路径、fetch、Service Worker 全部失效。
正确做法只有两种：
- 用
npx serve out启一个本地 HTTP 服务（推荐，零配置） - 部署到支持静态托管的平台，如 GitHub Pages、Vercel、Netlify；注意 GitHub Pages 需配置
basePath（如果不在根路径）
另外，若项目用了 next-pwa，其生成的 service-worker.js 默认路径是根目录，部署到子路径时需在 next.config.js 中显式设 swcMinify: true 和 basePath，否则注册失败。
