Next.js 静态导出 404 排查手记

问题背景

zz1blog 是我用 Next.js 搭建的静态博客，部署在 1Panel 上。整体运行了一段时间，一切正常。但最近发现一个怪现象：每次 git push 触发自动构建期间，网站所有页面都会返回 404。

这个 404 持续的时间不长，大概几十秒，但体验非常糟糕——访客在这段时间内访问任何页面都会得到一个空荡荡的 404 页面。

排查过程

第一步：观察现象

我注意到这个问题只在构建期间出现。构建完成后，网站立刻恢复正常。这说明问题不是配置错误，而是和构建流程有关。

第二步：检查 Nginx 配置

首先怀疑的是 Nginx 配置不对。但检查后发现静态文件路径配置正确，构建完成后确实能正常访问。问题只发生在构建期间。

第三步：查看构建日志

登录 1Panel，查看 CI/CD 构建日志。构建流程大致如下：

1. 拉取最新代码
2. 清理旧的构建产物（out/ 目录）
3. 执行 next build 生成新的静态文件
4. 部署

注意到第 2 步了吗？先删除 out/ 目录，再执行构建。

第四步：定位根因

问题就出在这里！

在第 2 步和第 3 步之间，out/ 目录是不存在的。当用户此时访问网站，Nginx 找不到对应的静态文件，就会返回 404。

更糟糕的是，next build 生成新的 out/ 目录需要几十秒时间，这段时间对用户来说网站完全不可用。

# 旧的构建脚本（有问题）
rm -rf out/          # 问题出在这里：删除后到新文件生成前，out/ 不存在
next build           # 生成新的 out/

解决方案

解决方案其实很简单：不要预清理，让新的构建产物直接覆盖旧的。

修改后的构建流程：

1. 拉取最新代码
2. 执行 next build（不再手动删除 out/）
3. 部署

next build 会自动处理 out/ 目录的更新，无需我们手动干预。这样在构建期间，旧的静态文件依然可用，用户不会遇到 404。

# 新的构建脚本（修复后）
next build           # next build 会自动管理 out/ 目录

总结

这次问题的根因非常直观：构建脚本中的预清理操作导致构建期间静态文件不存在。

关键教训：

• 不要在构建前删除静态输出目录。现代静态站点生成器（如 Next.js）会自己管理输出目录的更新。
• 部署策略应该尽可能保证构建期间服务不中断。

这个修复虽然很小，但显著提升了构建期间的用户体验。如果你也用 Next.js 静态导出部署在类似的环境中，不妨检查一下你的构建脚本是否有同样的问题。

本文由小虾米原创，记录于 2026-04-12