frankenphp 本地开发可直接运行 laravel 等主流框架，无需 nginx+php-fpm；常见空白页或报错多因 caddyfile 路径错误、root 未指向 public/、缺 php_server 块或 worker 模式掩盖启动异常，调试应先禁用 worker 并启用 -debug 查看终端日志。
FrankenPHP 本地开发环境能直接跑 Laravel、Symfony、ThinkPHP 等主流框架，无需 Nginx + PHP-FPM 拆分配置，但安装后 frankenphp run 报错或访问空白页，90% 是 Caddyfile 路径、PHP 入口或 worker 模式开关没对齐。
确认系统支持并下载正确二进制
FrankenPHP 不依赖系统 PHP，它自带静态链接的 PHP 8.5 运行时，但对系统 glibc（Linux）或 macOS 版本有硬性要求：
- Linux：glibc ≥ 2.28（Ubuntu 20.04+/CentOS 8+ 可用；Debian 10 或更老版本需用
musl静态版） - macOS：≥ 12.0（M1/M2 芯片选
arm64，Intel 选amd64） - Windows：仅支持 Windows 10 18362+，推荐用 WSL2 而非原生 CMD/PowerShell（避免
fork()相关权限错误）
下载后别直接双击运行。终端执行：chmod +x frankenphp && ./frankenphp --version。若报 cannot execute binary file，说明架构不匹配；若报 command not found，说明没加到 PATH 或文件名不是 frankenphp（官方二进制无后缀）。
Caddyfile 必须放在项目根目录且 root 指向 public/
FrankenPHP 默认只读当前目录下的 Caddyfile，不会向上查找。Laravel、Symfony、ThinkPHP8 等现代框架都要求 Web 入口为 public/ 子目录，否则会暴露 config/、vendor/ 等敏感路径。
一个最小可用的 Caddyfile 应该长这样：
{ frankenphp }
localhost {
root * public/
php_server {
try_files {path} /index.php
}
encode zstd br gzip
}
注意三点：
-
root * public/中的*表示匹配所有请求路径，不能写成root public/（语法错误） -
try_files {path} /index.php是 Laravel/Symfony 路由必需的——它把所有非静态资源请求兜底转发给public/index.php，缺了就会 404 - 不要在
php_server块外写rewrite或handle，FrankenPHP 的php_server已内置重写逻辑，重复处理会导致循环重定向
调试时先禁用 worker 模式
worker 模式让 PHP 进程常驻内存，提升性能，但会掩盖启动期错误。比如 .env 缺失、数据库连接失败、OPcache 配置冲突等，都会导致服务静默退出，frankenphp run 看似成功，浏览器却返回空白页或 500。
临时关闭方法有两种：
- 命令行启动时加
--no-worker：frankenphp run --no-worker - 在
Caddyfile全局块里显式关闭：{ frankenphp { worker off } }
关闭后，每次请求都会重新加载整个应用，错误会直接打印在终端日志里（如 Class 'App\Http\Controllers\Controller' not found），而不是被 worker 进程吞掉。确认功能正常后再开 worker on 或删掉 worker off。
常见 500 错误的快速定位路径
FrankenPHP 不生成传统 PHP-FPM 的 slow log 或 access log，调试靠三件事：
- 终端输出：启动时加
-debug参数，frankenphp run -debug会显示每个请求的完整生命周期和 PHP 错误 - 检查
public/index.php是否存在且可读（权限应为 644，不能是 600） - 确认
php.ini相关设置已生效：FrankenPHP 会读取frankenphp/php.ini（同级目录）或环境变量FRANKENPHP_PHP_INI_PATH，但默认不加载系统/etc/php/下的配置
如果 var_dump($_SERVER) 显示 REQUEST_URI 为空，大概率是 Caddyfile 里漏了 php_server 块；如果看到 Failed to open stream: No such file or directory，基本是 root 路径写错了，或者 public/ 下没有 index.php。
worker 模式下 PHP 进程常驻，但它的生命周期独立于 Caddy 的 HTTP 连接管理——这意味着你改了 .env 或 config/app.php，必须重启 frankenphp 才生效，热重载只对纯 PHP 文件有效，不包括框架配置。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
