Nginx 不实现 ISR，而是通过透传缓存头（如 stale-while-revalidate）并代理 next start 服务来配合 Next.js 的 ISR 工作流；需禁用 proxy_ignore_headers 覆盖、启用 proxy_cache 并验证响应头与再生日志。
Next.js 的静态增量再生（ISR）在构建时生成静态页面，运行时按需更新，但前提是服务端支持 stale-while-revalidate 语义和缓存控制。Nginx 本身不执行 ISR 逻辑（那是 Next.js Server Side Rendering 或中间件的事），但它可以高效代理、缓存并透传 ISR 所需的请求头与响应头，让 Next.js 应用（如 next start）真正发挥 ISR 能力。关键不是“Nginx 实现 ISR”，而是“Nginx 正确配合 Next.js 的 ISR 工作流”。
确认 Next.js 已启用 ISR 并正确导出
确保你的页面组件使用了 getStaticProps 并配置 revalidate：
export async function getStaticProps() {
return {
props: { /* ... */ },
revalidate: 60 // 每 60 秒尝试再生
};
}注意：ISR 仅在 next start（Node.js 服务模式）下生效，next export 不支持 ISR。因此你必须运行 next start（默认监听 localhost:3000），再由 Nginx 反向代理它。
配置 Nginx 代理并透传关键请求/响应头
Nginx 需做到三件事：1）把请求准确转发给 Next.js 服务；2）允许客户端和服务端自由传递缓存相关头；3）不覆盖 Next.js 返回的 Cache-Control 和 Set-Cookie 等关键响应头。以下是最小可靠配置片段：
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
<h1>⚠️ 关键：不强制覆盖 Cache-Control，允许 Next.js 自行控制</h1><p>proxy_ignore_headers Cache-Control Expires Set-Cookie;</p><h1>可选：为 HTML 资源启用本地缓存（仅当 Next.js 已返回 public, max-age=...）</h1><p>proxy_cache my_cache;
proxy_cache_valid 200 301 302 60s;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_lock on;
}说明：
-
proxy_ignore_headers Cache-Control Expires Set-Cookie是核心——防止 Nginx 错误覆盖 Next.js 响应中带stale-while-revalidate的Cache-Control头（例如public, max-age=0, must-revalidate, stale-while-revalidate=60） -
proxy_cache启用后，Nginx 会缓存 HTML 响应，但只在 Next.js 明确返回可缓存响应时才生效；它不会干扰 ISR 再生逻辑，因为再生请求仍会原样发往 Next.js（通过proxy_cache_use_stale+ 后台更新机制实现“过期仍返回旧内容+异步刷新”） - 无需手动设置
X-Forwarded-For以外的其他头来触发 ISR——Next.js 依赖的是自身服务端逻辑和响应头，不是客户端 IP 或 UA
验证 ISR 是否实际生效
部署后，用浏览器或 curl 检查关键点：
- 访问页面，查看响应头是否含
Cache-Control: public, max-age=0, must-revalidate, stale-while-revalidate=60（数值与revalidate设置一致） - 首次访问后等待超 60 秒，再次访问该页面：
– 若看到旧内容且响应状态是200（非304），说明 Nginx 或浏览器命中了 stale 缓存；
– 查看 Next.js 服务日志，应有Regenerating page...日志，证明后台再生已触发 - 禁用浏览器缓存重试（如 Chrome DevTools → Network → Disable cache），可排除浏览器层干扰，专注服务端行为
常见陷阱与绕过建议
以下情况会导致 ISR “看似失效”：
-
用了
next export静态导出：ISR 必须搭配next start，不能用于纯静态站点 -
Nginx 强制设置了
Cache-Control：检查是否有add_header Cache-Control ...或未加proxy_ignore_headers，这会覆盖 Next.js 的精细控制 -
开发环境误测：ISR 在
next dev下被禁用，务必用next build && next start测试 -
CDN 层拦截/覆盖缓存头：若前端还套了 Cloudflare 或 CDN，需确保它们不修改或删除
Cache-Control中的stale-while-revalidate字段
