健康检查接口应绕过框架直接响应：在public/index.php顶部添加短路逻辑，判断请求路径匹配配置的health_check_path后，手动设置Content-Length和Content-Type头，输出JSON并exit。
健康检查接口返回 502/503 而不是预期的 200
负载均衡器（如 Nginx、ALB、SLB）默认会周期性请求一个路径做健康检查，但 ThinkPHP 的路由机制可能让该请求被中间件拦截、重定向，或触发未初始化的数据库连接——结果就是返回 502（Bad Gateway）或 503（Service Unavailable），而非你写的 return json(['status' => 'ok'])。
解决关键是：绕过所有业务逻辑层，让健康检查路径在框架最底层就响应。不要用常规控制器，改用「裸响应」方式。
- 在
public/index.php顶部加一段短路逻辑（放在require __DIR__ . '/../thinkphp/start.php';之前）： - 判断
$_SERVER['REQUEST_URI'] === '/health'（或你配置的路径），直接输出HTTP/1.1 200 OK和 JSON，然后exit - 确保 Web 服务器（如 Nginx）不把
/health转发给 PHP-FPM 以外的路径——否则这段代码根本不会执行
ThinkPHP 中间件干扰健康检查响应
即使你写了 HealthController，中间件（比如 CheckAuthMiddleware、BindModelMiddleware）仍可能提前终止请求或抛异常。健康检查不需要鉴权、不需要 DB 连接、甚至不该加载应用配置。
最稳妥的做法是：不在应用层处理健康检查，而是在入口文件短路；如果必须走框架路由，则需显式禁用中间件。
立即学习“PHP免费学习笔记（深入）”；
- 在路由定义中使用
withoutMiddleware()：Route::get('health', 'Health/check')->withoutMiddleware(); - 确认该路由没被全局中间件组（如
app/middleware.php中的['http' => [...]]）覆盖 - 避免在
check()方法里调用Db::table()->count()等依赖数据库的操作——DB 连接池可能未就绪，导致超时或 500
多环境配置下健康检查路径不一致
开发环境用 /health，测试环境用 /ping，生产环境又变成 /actuator/health——这些差异若硬编码在路由或中间件里，极易漏配、错配。
应该把健康检查路径抽成配置项，由部署环境决定，而不是写死。
- 在
config/app.php中加一项：'health_check_path' => env('HEALTH_CHECK_PATH', '/health') - 入口文件短路逻辑中读取：
if ($_SERVER['REQUEST_URI'] === config('app.health_check_path')) { ... } - CI/CD 发布时通过
.env注入：HEALTH_CHECK_PATH=/ping，无需改代码
负载均衡器主动断连导致假阴性
某些 LB（如 AWS ALB）对健康检查响应有严格限制：超时时间默认 5 秒、要求响应头含 Content-Length、拒绝 chunked transfer encoding。而 ThinkPHP 默认开启输出缓冲，且未设 Content-Length，可能导致 LB 认为服务不可用。
这不是框架 bug，而是协议适配问题。必须显式控制响应头和输出行为。
- 短路逻辑中手动设置：
header('Content-Length: 13'); header('Content-Type: application/json; charset=utf-8'); - 避免使用
echo json_encode(...)后再exit，改用fastcgi_finish_request()（PHP-FPM 场景）或直接ob_end_clean(); echo ...; exit; - 禁用 ThinkPHP 的自动输出压缩（
output_compression配置设为false），否则 LB 可能无法解析 gzip 响应
健康检查真正的难点不在“怎么写个 200”，而在于它必须在框架加载前、DB 连接外、中间件外、压缩外、缓冲外——稳稳地落在那 13 个字节上。漏掉任意一环，LB 就会默默把你踢出节点池。
