FrankenPHP迁移后代码回滚必须用软链接切换而非直接覆盖，因其单进程嵌入式模型不支持热加载，硬覆盖易致OPcache混跑、Fatal error；需配合清OPcache、Redis缓存及Worker进程重启。
FrankenPHP迁移后代码层回滚必须用软链接切换，不能直接覆盖
FrankenPHP本身是单进程嵌入式模型，没有PHP-FPM那种多进程热加载机制，一旦你用git checkout或rsync -av直接覆盖线上文件，旧版本的PHP字节码可能还卡在OPcache里，新旧代码混跑极容易触发Fatal error: Class 'X' not found或Cannot redeclare function。更麻烦的是，FrankenPHP启动时会预编译部分PHP文件进内存，硬覆盖后不重启服务根本无效。
稳妥做法是把不同版本项目目录隔离存放，用软链接指向当前生效版本：
- 部署时把旧版目录保留为
/var/www/myapp-v1.2.3，新版为/var/www/myapp-v1.3.0 - 用
ln -sf /var/www/myapp-v1.2.3 /var/www/current切版本 - 回滚只需再执行一次
ln -sf，毫秒级完成，且不干扰FrankenPHP主进程 - 务必在Caddyfile中用
root * /var/www/current/public而非绝对路径，否则软链接失效
数据库迁移必须配对回滚，不能只退代码
Laravel的php artisan migrate:rollback在FrankenPHP下照常可用，但关键点在于：它只管migrations表和down()逻辑，不管你的up()里是否写了破坏性操作（比如DROP COLUMN）。一旦执行过，回滚就无法恢复字段——这和PHP-FPM环境完全一样，但FrankenPHP用户容易误以为“换回旧代码就万事大吉”。
真实回滚场景要分三类处理：
立即学习“PHP免费学习笔记（深入）”；
- 纯结构变更（如新增字段）：
migrate:rollback能安全执行，前提是down()方法写得完整 - 破坏性变更（如
DROP TABLE）：必须提前备份全量表结构+数据，回滚时用mysqldump还原，不能依赖框架迁移 - 数据填充类变更（如
DB::table('settings')->insert(...)）：框架迁移不支持自动反向，得手写down()删记录，或靠备份快照
建议在迁移前用php artisan migrate:status确认当前版本号，并把该版本号写进发布日志——回滚时直接对应到migrate:rollback --step=1还是--to=2024_05_01_120000_create_users_table。
OPcache和Redis缓存必须强制清空，FrankenPHP不会自动感知代码切换
FrankenPHP的OPcache默认开启且缓存时间长，即使你切了软链接，opcache_get_status()['scripts']里仍显示旧路径的PHP文件被缓存。更隐蔽的是Redis里的Laravel配置缓存（php artisan config:cache生成的config.php）和路由缓存，它们和代码版本强绑定。
回滚脚本里这几步缺一不可：
- 执行
frankenphp opcache-reset（官方提供的CLI命令，比kill -USR2更可靠） - 清Redis所有键：
redis-cli FLUSHDB，或按前缀清理：redis-cli --scan --pattern "laravel:*" | xargs redis-cli DEL - 删掉
bootstrap/cache/config.php和bootstrap/cache/routes-v7.php这些缓存文件 - 如果用了
view:cache，顺手rm -f storage/framework/views/*
漏掉任意一项，都可能出现“代码已回退，但页面还是新逻辑”的诡异现象。
FrankenPHP的Worker模式回滚必须停进程再启，不能热切换
经典模式（Nginx替代）下回滚只需切软链接+清缓存；但Worker模式本质是常驻进程，PHP代码加载进内存后不会随文件变化而更新。你切了软链接、清了OPcache，Worker里跑的仍是旧字节码。
所以Worker模式回滚唯一正确姿势是：
- 先发信号停Worker：
frankenphp stop或kill -SIGTERM $(cat /var/run/frankenphp.pid) - 确认进程退出：
ps aux | grep frankenphp无残留 - 再用原启动命令重拉起：
frankenphp worker --caddyfile Caddyfile - 检查
curl http://localhost:8000/health返回状态，避免因.env未同步导致DB连接失败
这个过程必然有秒级业务中断，所以Worker模式上线前必须评估SLA容忍度——它性能更强，但回滚代价也更高。
最易被忽略的是Caddyfile里的php指令参数，比如php /var/www/current/public/index.php这种硬编码路径，一旦没随软链接更新，FrankenPHP会静默加载错误版本的入口文件，连错误日志都不报。
