frankenphp_handle_request 返回 false 表示请求未被成功处理，常见原因包括：显式返回 false（如权限校验失败）、函数末尾无 return 导致隐式返回 null（被视作 false）、调用 exit()/die() 中断执行、或框架初始化异常未捕获导致未返回 true。
frankenphp_handle_request 返回 false 的常见原因
frankenphp_handle_request 是 FrankenPHP worker 模式下 PHP 脚本的主入口函数，它负责接管单个请求并交由你的应用逻辑处理。返回 false 表示该请求**未被成功处理**，FrankenPHP 会将其标记为失败，并可能触发重试或记录错误日志（取决于配置）。这不是 PHP 报错，而是函数明确返回的布尔值，需主动检查和响应。
实际项目中，frankenphp_handle_request 返回 false 多数不是意外，而是你代码里显式返回、或隐式返回（如函数末尾无 return）导致的逻辑终止。它本身不抛异常，也不拦截 fatal error —— 那些会直接让 worker 进程崩溃，根本走不到返回值这步。
- 你手动写了
return false;，比如在权限校验失败、路由未匹配、或健康检查探针里主动拒绝请求 - worker 脚本顶层作用域执行完，没写
return true;，PHP 默认返回null，而 FrankenPHP 将null视为false（注意：不是类型严格比较，是松散判断） - 调用了
exit()或die()，导致后续代码不执行，函数自然返回false - 框架初始化失败（如 TP6 的
think\Container构建出错），但你没捕获异常，脚本中断，等效于未返回true
为什么返回 false 会导致请求无响应或 500
FrankenPHP 在 worker 模式下期望每个请求都得到明确的“已处理”信号。如果 frankenphp_handle_request 返回 false，它不会尝试重放请求，也不会 fallback 到普通模式；它只是把这次请求当作失败处理，并可能：
– 不发送任何 HTTP 响应头或 body
– 记录一条类似 request failed: handler returned false 的日志（默认级别为 warn）
– 在指标中增加 frankenphp_worker_requests_total{status="error"} 计数
用户侧表现通常是连接被重置、空响应、或 Nginx/Caddy 层回退到 502/500。尤其当使用 Caddy 作反代时，若未配置 handle_errors，就容易看到空白页。
立即学习“PHP免费学习笔记（深入）”；
- 返回
false≠ PHP 错误，所以error_log或display_errors不会起作用 - 必须检查 FrankenPHP 自己的日志（启动时加
-log-level=debug）才能看到 handler 返回 false 的上下文 - Caddyfile 中若启用了
php指令但未配worker，frankenphp_handle_request根本不会被调用——这点常被忽略
如何快速定位和修复
最直接的办法是在 worker 入口文件顶部加一层包装，强制捕获返回值并记录：
// worker.php
<?php
$result = frankenphp_handle_request();
if ($result === false) {
error_log('[FRANKENPHP] handler returned false at ' . date('c'));
// 可选：这里补发一个最小响应避免空返回
http_response_code(500);
echo 'Internal Server Error';
}
return $result;
同时确认以下三点是否满足：
- 入口文件路径与
composer.json中extra.frankenphp.worker值一致（例如"worker": "worker.php"） - worker 文件里没有未捕获的
ParseError或FatalError（可用php -l worker.php静态检查） - 所有分支路径最终都明确
return true;，不要依赖“执行到最后自动返回”
真正容易被忽略的是：TP6 等框架的 public/index.php 改造成 worker 入口时，原 require 后的 exit 必须删掉，且整个逻辑要包进 frankenphp_handle_request 回调里——否则 frankenphp_handle_request 根本不会被执行，更别说返回什么了。
