frankenphp部署laravel比nginx+php-fpm更简洁，但需注意四大高频问题：启动失败（frankenphp-worker.php缺失或无执行权限）、php扩展未启用（如pdo_mysql、mbstring等）、$_server等全局变量在worker模式下冻结导致请求异常、caddyfile配置错误（如root路径、try_files缺失）。
FrankenPHP 部署 Laravel 项目整体比 Nginx + PHP-FPM 更简洁，但切换过程中确实有几个高频、易踩、且容易被忽略的问题。这些问题集中在环境准备、启动流程、运行模式差异和配置细节上，而不是 Laravel 本身代码逻辑。
启动失败：frankenphp-worker.php 缺失或不可执行
这是最常遇到的卡点，尤其在使用 Laravel Octane 的 worker 模式时。
- 必须先运行 php artisan octane:install --server=frankenphp，仅安装 laravel/octane 包不等于完成 FrankenPHP 集成
- 安装命令会下载 FrankenPHP 二进制并生成
vendor/bin/frankenphp-worker.php，若网络中断或权限受限，该文件可能为空或缺失 - 检查是否存在且可执行：
ls -l vendor/bin/frankenphp-worker.php；如无执行权限，运行chmod +x vendor/bin/frankenphp-worker.php - Docker 或 CI/CD 构建中，
octane:install常被静默跳过——建议在构建脚本末尾加一行验证命令
经典模式下“零改动”不成立：PHP 扩展缺失
FrankenPHP 自带 PHP 运行时，但它不自动启用所有扩展。Laravel 启动报错如 Class 'PDO' not found 或 mbstring extension is required，基本都源于此。
- 用
frankenphp php-cli -m查看已启用的内置扩展，确认pdo_mysql（或pdo_pgsql）、mbstring、openssl、json、xml、bcmath、fileinfo等是否在列 - Docker 场景下，需在
Dockerfile中显式安装扩展，例如：RUN install-php-extensions pdo_mysql redis mbstring opcache - 本地二进制部署时，某些扩展（如
redis）需手动编译或依赖系统库，建议优先用 Docker 镜像避免兼容问题
Worker 模式下请求行为异常：$_SERVER 冻结与状态残留
一旦开启 Octane + FrankenPHP 的 worker 模式，PHP 进程常驻内存，$_SERVER、$_GET、静态变量等不再随每次请求重置。
-
$_SERVER['REQUEST_URI']、$_SERVER['HTTPS']、$_SERVER['HTTP_HOST']在首次请求后就固化，后续请求读取会出错——应统一改用request()->fullUrl()、request()->secure()、request()->getHost() - 避免在服务提供者
register()或bootstrap/app.php中基于请求头做逻辑分支（比如按域名加载不同配置），这类代码只执行一次 - 静态变量、全局缓存、单例对象会在请求间共享，未清理会导致数据污染或内存泄漏；如有必要，应在
App\Providers\AppServiceProvider::boot()中监听Octane\RequestReceived事件重置上下文
Caddyfile 配置偏差导致 404 或空白页
FrankenPHP 的 Caddyfile 不是 Nginx 配置的简单翻译，几个关键项写错就会让路由失效。
-
root必须指向public/目录，不是项目根目录；否则index.php找不到，所有请求 404 -
php_server块内必须包含try_files {path} index.php，缺了这句，Laravel 的前端控制器机制无法触发 - 若使用自定义域名，
SERVER_NAME环境变量或 Caddyfile 中的站点地址要与 DNS 解析一致；本地测试用localhost时，Caddy 会自动签发证书，但浏览器需手动接受自签名提示 - HTTP/3 支持需同时暴露 TCP 443 和 UDP 443 端口，Docker 中漏掉
-p 443:443/udp会导致 QUIC 协议降级
这些问题大多有明确触发条件和对应解法，不复杂但容易忽略。只要在迁移前跑通 frankenphp php-cli -v 和 php artisan octane:install --server=frankenphp，再对照 Caddyfile 样例逐项核对路径与指令，就能避开绝大多数上线障碍。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
