FrankenPHP 迁移无需重构项目，但需验证 composer.json 的 PHP 版本约束、扩展可用性及 vendor/ 兼容性，推荐在 FrankenPHP 环境下重新执行 composer install --no-dev --optimize-autoloader。
FrankenPHP 本身不改变你的 PHP 项目结构，迁移时不需要重写或重构 Composer 依赖，但必须验证和可能调整依赖的安装方式与运行环境。
FrankenPHP 运行时对 Composer 的兼容性要求
FrankenPHP 内置的是静态链接的 PHP（如 Linux 版默认带 PHP 8.5），它不依赖系统 PHP，但会严格遵循 PHP 版本语义。这意味着：
- 你的
composer.json中声明的"php"约束（例如"^8.1"）必须与FrankenPHP实际提供的 PHP 版本兼容；若 FrankenPHP 是 8.5，而你锁死在"~7.4.0"，composer install会直接失败 - 扩展依赖不能假设系统级安装——比如
ext-redis或ext-pdo_pgsql若未被 FrankenPHP 编译进二进制，默认不可用；要查官方发行版的php -m输出确认已启用模块 - 某些包（如
symfony/cli、laravel/installer）含平台脚本或二进制依赖，它们在 FrankenPHP 的嵌入式环境中可能无法执行，应移出require-dev或改用纯 PHP 替代方案
vendor/ 能否直接复用？关键看 PHP 小版本和扩展一致性
如果你是从系统 PHP 迁移到 FrankenPHP，vendor/ 目录不是“一定不能用”，而是“必须验证后才敢用”：
- 运行
php -v对比源环境与FrankenPHP的完整版本号（如8.2.12vs8.2.15）：小版本不一致可能导致 opcache 行为差异或扩展 ABI 不兼容 - 检查关键扩展是否都存在：
mbstring、openssl、json、curl、pdo_sqlite（尤其 Koel 默认用 SQLite）——缺一不可 - 最稳妥做法是删掉
vendor/和composer.lock，在FrankenPHP环境下重新跑composer install --no-dev --optimize-autoloader - 若坚持复用旧
vendor/，务必在 FrankenPHP 下执行composer dump-autoload -o，否则 symlink 自动加载路径可能失效
离线部署时 vendor/ 和 cache 的打包逻辑要重理
FrankenPHP 常用于无网络主机（如嵌入式设备、内网服务器），此时离线迁移依赖不能只靠 vendor/ 复制：
立即学习“PHP免费学习笔记（深入）”；
- 若你用
composer install --prefer-dist生成过缓存，需打包完整~/.composer/cache/files/目录，并在目标机用composer config --global cache-files-dir /path/to/copied/cache指向它 -
composer.lock必须保留且不可手动编辑——FrankenPHP 下的composer install仍靠它校验 dist.shasum，一旦哈希不匹配就报Package not found - 常见坑：子依赖（如
psr/container）没进缓存，因为源机只跑了composer require laravel/framework，没触发全量安装；正确做法是先composer install --no-dev再打包缓存
FrankenPHP 的价值在于收敛部署栈，不是绕过 Composer。真正容易被忽略的点是：它把 PHP 运行时“固化”了，但 Composer 仍按 PHP 版本和扩展可用性做严格校验——你以为只是换了个 Web 服务器，其实已经换了整个 PHP ABI 环境。
