Next.js SSR应用需自建/api/health端点，NGINX Plus可配置主动健康检查，开源Nginx则依赖被动检查+外部探活工具，部署时须确保服务就绪后再接入流量并做好限流与缓存隔离。
Next.js 应用在 SSR（服务端渲染）模式下通常依赖 Node.js 服务（如 next start）提供动态页面和 API 路由。Nginx 作为反向代理，本身不直接感知后端健康状态；要实现真正的服务可用性监控，需配合自定义健康检查端点与 Nginx 的 health_check 指令（需启用 ngx_http_upstream_health_check_module，即商业版 NGINX Plus，或使用开源替代方案）。以下指南聚焦实用、可落地的部署与监控策略，兼顾开源 Nginx 用户。
1. 在 Next.js 中暴露健康检查端点
Next.js 默认不提供健康接口，需手动添加。推荐使用 pages/api/health.ts（或 .js）创建轻量级、无副作用的检查逻辑：
- 返回
200 OK，响应体可为{"status": "healthy", "timestamp": "..."} - 可选校验关键依赖（如数据库连接池、Redis 连通性），但避免耗时操作或写入行为
- 不验证会话、Token 或权限——健康检查应绕过业务中间件
- 示例代码：
export default function handler(req, res) { res.status(200).json({ status: 'healthy', timestamp: new Date().toISOString(), version: process.env.NEXT_PUBLIC_APP_VERSION || 'dev' }); }
2. 配置 Nginx upstream 与主动健康检查（NGINX Plus）
若使用 NGINX Plus（支持原生 health_check），可在 upstream 块中启用主动探测：
- 指定
health_check参数，设置路径、间隔、失败阈值等 - 确保 SSR 服务监听地址（如
localhost:3000）已加入 upstream - 示例配置：
upstream nextjs_backend { server 127.0.0.1:3000 max_fails=3 fail_timeout=30s; health_check interval=5s uri="/api/health" fails=2 passes=2; } - 注意：该功能 仅限 NGINX Plus，开源 Nginx 不支持原生主动健康检查
3. 开源 Nginx 的替代方案：被动健康检查 + 自定义探活
对于标准开源 Nginx，虽无主动探测，但可通过组合方式实现有效监控：
- 启用
max_fails和fail_timeout实现被动健康判断（基于请求失败统计） - 搭配外部工具（如
curl+systemd定时任务 或consul-template）定期调用/api/health，失败时触发 reload 或告警 - 在 Nginx 日志中记录健康端点访问（
location /api/health { access_log /var/log/nginx/health.log; }），便于审计与排查 - 将健康检查路径排除在缓存规则之外（避免被
proxy_cache缓存）
4. 部署注意事项与最佳实践
确保整个链路稳定可靠：
- SSR 服务启动后，等待健康端点就绪再将流量接入（可借助
wait-on工具或容器就绪探针） - Nginx 配置中，
proxy_pass应指向 upstream 名称而非硬编码地址，便于扩展与维护 - 为健康端点设置独立限流（
limit_req），防止被恶意刷量影响主服务 - 在 CI/CD 流程中集成健康端点验证（
curl -f http://localhost:3000/api/health），作为部署前置检查
