FrankenPHP 在 ARM 架构服务器安装踩坑记录-php教程-PHP中文网

frankenphp官方ppa不支持arm64架构，需手动下载github发布的_arm64二进制包；其内置php运行时abi与系统php不兼容，扩展须用frankenphp自带php-config编译；arm部署时须显式配置caddyfile root路径并谨慎设置worker数量防oom。

frankenphp 在 arm 架构服务器安装踩坑记录

FrankenPHP 官方包不支持 arm64，别直接 apt install

FrankenPHP 官方 PPA（ppa:frankenphp/stable）只提供 x86_64 架构的二进制，apt install frankenphp 在 ARM 服务器上会报错“no installation candidate”或直接跳过。这不是你源没配对，是它压根没编译 arm64 版本。

实操建议：

去 GitHub Releases 页面手动下载 frankenphp_<version>_linux_arm64.tar.gz</version>（注意后缀含 _arm64）
解压后把 frankenphp 二进制丢到 /usr/local/bin/，并 chmod +x
验证：frankenphp -v 应输出版本号，且 file frankenphp 显示 “aarch64”

PHP 扩展必须与 FrankenPHP 内置 PHP ABI 严格匹配

FrankenPHP 自带嵌入式 PHP 运行时（非系统 PHP），所以 php -v 和 frankenphp -v 显示的 PHP 版本、扩展 ABI 可能完全不同。用系统 phpize 编译的扩展（比如 redis.so）加载会失败，错误类似：

PHP Warning:  PHP Startup: Unable to load dynamic library 'redis.so' (tried: /usr/lib/php/20220829/redis.so (libredis.so: cannot open shared object file: No such file or directory), /usr/lib/php/20220829/redis.so.so (/usr/lib/php/20220829/redis.so.so: undefined symbol: redis_serialize))

根本原因是扩展 ABI 不兼容，不是路径或依赖缺失。

实操建议：

先运行 frankenphp -m 看已启用哪些模块，确认是否已内置常用扩展（如 pdo_mysql, opcache）
如需额外扩展，必须用 FrankenPHP 自带的 php-config（通常在同目录下）配合源码编译，例如：
./configure --with-php-config=/path/to/frankenphp/php-config
更稳妥的做法：优先用纯 PHP 实现的包（如 phpredis 的纯 PHP client），绕过扩展依赖

Caddyfile 中的 `php` 指令在 ARM 上需显式指定 `root`

在 x86 上常写的简写配置：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

route {
    php
    file_server
}

在 ARM 服务器上容易触发 404 或空白响应，尤其 Laravel 项目。因为 FrankenPHP 的 php 指令默认从当前工作目录找 index.php，而 ARM 环境下 systemd 服务启动时 WorkingDirectory 常被忽略或设为 /，导致找不到入口文件。

实操建议：

务必显式声明 root 和 index：

route {
    root * /var/www/html
    php {
        index index.php
    }
    file_server
}

检查 ls -l /var/www/html/index.php 权限，确保运行用户（如 www-data）可读
如果用 php artisan octane:install --server=frankenphp，生成的 Caddyfile 里 root 是相对路径，要手动补全为绝对路径

Worker 模式下 `max_workers` 设置不当会导致 OOM

ARM 服务器（尤其是鲲鹏 920、飞腾等）内存通常比 x86 服务器紧张，而 FrankenPHP 的 worker 模式会让每个 worker 常驻一个完整 PHP 进程（含框架初始化内存）。Laravel 项目单个 worker 启动后常驻内存可能达 80–120 MB。若按 x86 经验设 max_workers 10，在 2 GB 内存的 ARM 机器上很快就会被 OOM killer 干掉。

实操建议：

先用 frankenphp run --workers=1 单 worker 跑通，再用 ps aux --sort=-%mem | head -5 观察单个 frankenphp 进程 RSS
根据可用内存保守设置：max_workers = floor((total_memory_mb - 512) / avg_worker_rss_mb)
在 Caddyfile 中明确限制：
```
php {
    workers 2
}
```
搭配 opcache.enable=1 和 opcache.memory_consumption=256（写在 php.ini 或 FrankenPHP 的 php_options 块里），减少重复脚本加载开销