零改动迁移仅在经典模式下成立，即用FrankenPHP直接替代Nginx+PHP-FPM，Laravel代码无需修改；Worker模式需装laravel/octane并满足无状态要求，不属零改动。
frankenphp 迁移中途卡住、报错、页面空白或 502，大概率不是“不兼容”，而是你误入了 Worker 模式却没做适配——经典模式（即纯 frankenphp 替代 nginx + php-fpm）本身对 Laravel、Symfony、WordPress 等传统 PHP 项目是零代码改动的。
确认你当前用的是经典模式还是 Worker 模式
很多人迁移失败，第一反应是“FrankenPHP 不兼容我的项目”，其实只是启动方式错了。
- 经典模式：直接运行
frankenphp web或用 Caddyfile 启动，public/index.php入口照常走，$_SERVER、$_GET、file_get_contents('php://input')全部原样可用，Laravel 的APP_URL、SESSION_DRIVER、LOG_CHANNEL等环境变量也不需要改 - Worker 模式：必须显式启用
worker { file "bootstrap/app.php" }，且要求应用无状态——不能依赖全局变量、不能在index.php里写new App()、不能用register_shutdown_function做资源清理，更不能在请求中修改$_SERVER或静态属性
如果你没改过 Caddyfile、也没执行过 php artisan octane:start，那默认就是经典模式。此时报错，90% 是扩展缺失或路径配置问题。
经典模式下最常踩的三个坑
经典模式虽零改动，但 FrankenPHP 内置的 PHP 运行时和你本地 PHP 版本/扩展不完全一致，容易在启动瞬间就失败。
立即学习“PHP免费学习笔记（深入）”；
-
frankenphp php-cli -m输出里缺pdo_mysql或mbstring？立刻补装：install-php-extensions pdo_mysql mbstring openssl（Docker 场景）或用frankenphp install-php-extensions（二进制场景） -
public/不在根目录？FrankenPHP 默认只认./public。如果你项目结构是src/+web/，要么软链ln -sf web public，要么在 Caddyfile 里加root * /app/web - HTTPS 自动跳转失败？检查 Caddyfile 是否含
redir https://{http.request.hostport}{http.request.uri} permanent—— FrankenPHP 不会自动帮你加这个，Nginx 里写的return 301规则得手动搬过来
Windows 上迁移失败优先查什么
FrankenPHP 确实已原生支持 Windows（2026年3月起），但和 Linux 行为仍有细微差异，尤其涉及路径和扩展加载。
- 扩展名必须是
.dll，不是.so；用frankenphp php-cli -m看不到redis？说明php_redis.dll没放对位置——它得在C: rankenphpext下，且php.ini里写的是extension=php_redis.dll，不是extension=redis - 路径分隔符别硬写
/：Windows 下__DIR__ . '/config/app.php'没问题，但realpath('C:/project/config')可能返回 false，建议统一用str_replace('\', '/', $path)归一化 - 别信
phpinfo()显示的Loaded Configuration File路径：FrankenPHP 在 Windows 上默认不读系统php.ini，而是用内置 ini，想改配置得用 Caddyfile 里的php_ini指令，例如：php_ini date.timezone "Asia/Shanghai"
实在跑不起来？退回最小可行路径
别花时间调 Caddyfile 或重写路由。最稳妥的兜底做法是：删掉所有自定义配置，回到 FrankenPHP 默认行为。
- 删掉
Caddyfile，直接运行frankenphp web --document-root ./public - 确保
public/index.php存在且可读，且该目录下有index.html（用于验证静态文件是否通） - 用
curl -v http://localhost:8080和curl -v http://localhost:8080/index.php分别测，前者应返回 404 或 index.html，后者应触发 PHP 执行 - 如果
index.php报 500，看终端输出的错误——95% 是require路径错、扩展没加载、或opcache.enable_cli=1导致 CLI 模式下缓存冲突（关掉即可）
Worker 模式是性能优化项，不是必选项；经典模式才是 FrankenPHP 的默认交付形态。迁一半出问题，优先怀疑配置和扩展，而不是框架兼容性。
