Worker脚本必须用PHP CLI模式启动,不能走HTTP SAPI;需自行维持循环、调用$worker->wait()监听任务,并通过frankenphp.yaml显式配置路由绑定。

Worker 脚本必须用 PHP CLI 模式启动,不能走 HTTP SAPI
FrankenPHP 的 Worker 是独立于 HTTP 请求生命周期运行的长期进程,它不经过 php-fpm 或 Web 服务器 SAPI,而是由 FrankenPHP 主进程直接调用 php CLI 二进制执行。如果你用 echo "hello" 写了个普通脚本就扔进去,它会立刻退出——Worker 必须自己维持循环,且不能依赖 $_SERVER 等 CGI 变量。
实操建议:
- 脚本开头加
#!/usr/bin/env php(可选,但推荐) - 确保入口文件有可执行权限:
chmod +x worker.php - 不要在脚本里调用
exit()或未捕获异常退出,否则 Worker 进程崩溃后 FrankenPHP 默认不会自动重启(除非配置了restart: always) - CLI 模式下
ini_set('display_errors', '1')有效,错误会输出到 FrankenPHP 日志(通常是stderr)
使用 frankenphp\Worker 类处理任务队列
FrankenPHP 提供了原生 PHP 扩展类 frankenphp\Worker,用于接收主进程分发的任务(如 HTTP 请求、定时事件、自定义消息)。它不是轮询,而是阻塞式等待,底层基于 Unix socket 或内存通道通信。
常见错误现象:直接 new Worker() 后没调用 wait(),或在 wait() 外写业务逻辑,导致任务永远不被消费。
实操建议:
- 必须调用
$worker->wait()进入监听循环,否则脚本立即结束 -
wait()返回一个frankenphp\Task实例,类型由$task->type区分("http"、"timer"、"custom") - HTTP 类型任务需手动调用
$task->respond(),否则连接挂起 - 示例片段:
<?php use frankenphp\Worker;
use frankenphp\Task;$worker = new Worker();
while ($task = $worker->wait()) {
if ($task->type === 'http') {
$task->respond("HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n\r\nHello from Worker!");
} elseif ($task->type === 'timer') {
error_log("Timer fired at " . date('c'));
}
}
如何触发 Worker 接收 HTTP 请求?要配 frankenphp.yaml
Worker 不会自动接管所有请求——必须显式声明哪些路由交由哪个 Worker 处理。光写好 PHP 脚本没用,FrankenPHP 根本不会启动它。
使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。
实操建议:
- 在项目根目录放
frankenphp.yaml,写明workers:列表 - 每个 worker 条目需指定
script:(路径相对于配置文件)、concurrency:(可选)、env:(可选) - HTTP 路由通过
routes:绑定到具体 worker 名(name:),不是文件名 - 错误配置示例:
script: ./worker.php但实际路径是./src/worker.php→ 启动失败,日志报failed to exec worker script
最小可用配置示例:
workers: - name: "api-worker" script: "./worker.php" concurrency: 2routes:path: "/api/.*" worker: "api-worker"
调试 Worker 崩溃:看日志 + 加 try/catch + 避免全局状态
Worker 进程崩溃时通常静默退出,FrankenPHP 只在日志里记一行 worker exited with code X。最常见原因是未捕获异常、资源泄漏(如 PDO 连接未关闭)、或用了非线程安全的扩展(如某些旧版 ext-memcached)。
实操建议:
- 所有
wait()循环外层套try/catch (Throwable $e),并error_log($e) - 避免在 Worker 全局作用域初始化单例(如数据库连接),应在每次
$task处理中按需创建+释放 - CLI 模式默认不加载
.env,要用vlucas/phpdotenv就得手动Dotenv::createImmutable(__DIR__)->load(); - 检查
php --modules | grep frankenphp确认扩展已加载,否则new Worker()会报Class 'frankenphp\Worker' not found
复杂点在于:Worker 进程复用、无请求上下文、错误传播路径短——它不像 HTTP 请求那样有中间件兜底,任何未处理的异常都会终结整个进程。你得把它当 Go 的 goroutine 或 Node.js 的 worker thread 那样谨慎对待。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!










